@intentius/chant 0.122.0 → 0.123.0

package/dist/override-gate.d.ts

@@ -0,0 +1,224 @@
+/**
+ * The override gate (#3760, decision #3756): a person's recorded, reasoned
+ * decision to apply one plan a policy denied, spent once a run applies it.
+ *
+ * The policy engines stay in the products (OPA and conftest in terragucci,
+ * config rules in SQL Yodeler). They say a plan is denied and by which rules.
+ * This module records and decides the overrides of those denials, so a
+ * product keeps a thin layer over it:
+ *
+ * - A denial is a pending fact on `_gates/policy-override.jsonl` on
+ *   `chant/lifecycle`, gate the subject (a root, an environment, whatever the
+ *   product applies one plan to), with the rules that denied it
+ *   ({@link overridePending}). Its `planDigest` is the override digest
+ *   ({@link overrideDigest}), which binds the subject, the plan digest and
+ *   the rule ids, so `chant approve` copies it by default.
+ * - An override is an approval of that gate and digest, written with
+ *   `chant approve policy-override <subject> --rule <id> --reason <text>`
+ *   (`--sign` under `sealed`). The reason is its `note`.
+ * - It counts ({@link decideOverride}) when it is newer than the subject's
+ *   newest pending fact, names this digest, was written by a person the
+ *   overriders at base list ({@link overridersAt}), gives a reason, and under
+ *   `sealed` carries a seal that verifies for its approver against the
+ *   signers file at base. A line a job wrote (one that carries `via` or a
+ *   forge `review`) or an agent wrote never counts.
+ * - Before a run applies under an override it appends an applied record
+ *   ({@link appliedOverride}) to `_gates/policy-override/applied.jsonl`. An
+ *   override with an applied record is spent: it counts for nothing again, so
+ *   a plan that is denied again waits for its own override, and a spent
+ *   override of an older plan is not reported as a moved plan.
+ *
+ * Like `./gate-decision.ts` it reads the lines it is handed and writes
+ * nothing; `override-gate-bundle.test.ts` holds its import graph to the
+ * same bundle. chant's own writers are in `./lifecycle/override-ledger.ts`.
+ */
+import { type GateSigners } from "./workspace/trust/gate-seal.js";
+import type { GateResolutionRecord, PendingGateRecord } from "./lifecycle/gate-ledger.js";
+import type { GateApprovalSource } from "./op/op-waves.js";
+import type { GateAuditApply } from "./lifecycle/gate-audit.js";
+export type { GateResolutionRecord, PendingGateRecord } from "./lifecycle/gate-ledger.js";
+export type { GateSigners } from "./workspace/trust/gate-seal.js";
+/** The op every override and denial is recorded under. `./lifecycle/gate-audit.ts` reads this op as overrides by default. */
+export declare const OVERRIDE_OP = "policy-override";
+/** The ledger file on `chant/lifecycle` that holds denials and overrides. */
+export declare const OVERRIDE_LEDGER = "_gates/policy-override.jsonl";
+/** The file beside it that holds the overrides a run applied under. chant reads only the `.jsonl` files directly under `_gates/` as gate ledgers, so it never reads these lines as gate records. */
+export declare const OVERRIDE_APPLIED = "_gates/policy-override/applied.jsonl";
+/** Where the overriders are read at base when the caller names no other file: one principal per line, `#` starts a comment. */
+export declare const OVERRIDERS_PATH = ".chant/overriders";
+/** The rules as an override names them: trimmed, each once, sorted. */
+export declare function sortedRules(rules: readonly string[]): string[];
+/**
+ * The digest an override binds: the subject, its plan digest and the rules
+ * that denied it, as `sha256:<hex>` over their LF-joined lines after the op
+ * name. A plan that moved, or a different set of rules, gives another digest,
+ * so an override of one denial never lets another through.
+ */
+export declare function overrideDigest(subject: string, planDigest: string, rules: readonly string[]): string;
+/** The command that overrides a denial. */
+export declare function overrideCommand(subject: string, rules: readonly string[], sealed?: boolean): string;
+/** A denial's pending fact: the gate's record, with the plan it denied and the rules that denied it. `planDigest` is the override digest. */
+export interface OverridePendingRecord extends PendingGateRecord {
+    /** The plan digest the policy denied. */
+    plan: string;
+    /** The ids of the rules that denied it, sorted. */
+    rules: string[];
+}
+export interface OverridePendingInput {
+    subject: string;
+    planDigest: string;
+    rules: readonly string[];
+    /** ISO-8601. */
+    timestamp: string;
+    /** ISO-8601; past it a run that is still denied records a fresh fact. */
+    expiresAt: string;
+    description?: string;
+    runId?: string;
+    url?: string;
+}
+/** The pending fact a run records when the policy denies a plan and no override counts for it ({@link decideOverride} returns no `standing` fact). Appending it is the caller's. */
+export declare function overridePending(input: OverridePendingInput): OverridePendingRecord;
+/** The denials on the ledger: each subject's newest pending fact of the override op that names a plan. Sorted by subject. */
+export declare function recordedDenials(pending: readonly PendingGateRecord[]): OverridePendingRecord[];
+/** The overriders file at base. */
+export interface Overriders {
+    /** The commit it was read at. */
+    base: string | null;
+    path: string;
+    /** Whether the file exists at base. Without it nobody may override. */
+    active: boolean;
+    principals: string[];
+}
+/** The principals in an overriders file: one per line, blank lines and `#` comments skipped. */
+export declare function parseOverriders(text: string): string[];
+/**
+ * The overriders at `base` (a commit the repository holds, such as
+ * `baseCommit(repo)` from `@intentius/chant/gate-decision`), from `path`
+ * (default {@link OVERRIDERS_PATH}). Read at base, so the change being
+ * applied cannot add the person who overrides its own denial. A product that
+ * keeps its list in its own config at base reads it there and passes the
+ * principals to {@link decideOverride} instead.
+ */
+export declare function overridersAt(repo: string, base: string, path?: string): Overriders;
+/** A line of `_gates/policy-override/applied.jsonl`: a run applied under the override of `planDigest` made at `approvedAt`. */
+export interface AppliedOverrideRecord {
+    version: 1;
+    kind: "applied";
+    op: string;
+    /** The subject. */
+    gate: string;
+    /** The override digest. */
+    planDigest: string;
+    /** The override's own timestamp: every override of this digest at or before it is spent. */
+    approvedAt: string;
+    approvedBy: string;
+    /** When the run recorded it. */
+    timestamp: string;
+    runId?: string;
+    commit?: string;
+}
+/** The applied records in the text of an applied file. Malformed lines, and lines of another kind, are skipped. */
+export declare function parseAppliedOverrides(text: string): AppliedOverrideRecord[];
+/** What judges an override line: who may write one, the approval mode, and under `sealed` the signers at base. */
+export interface OverrideRule {
+    /** The principals who may override (an overriders file's, or a product's own list at base). */
+    overriders: readonly string[];
+    /** Where they were read, for the refusals. Default {@link OVERRIDERS_PATH}. */
+    overridersPath?: string;
+    /** `sealed` counts only a seal that verifies; `ledger` and `pr-review` count an unsealed override (an override is a person's line on the ledger, never a review). Default `ledger`. */
+    mode?: GateApprovalSource;
+    /** The signers at base (`gateSignersAt`). Under `sealed`, absent means nothing counts. */
+    signers?: GateSigners;
+}
+/** Why this ledger line does not count as an override, or null when it does. */
+export declare function overrideRefusal(rule: OverrideRule, r: GateResolutionRecord): string | null;
+export interface OverrideInput extends OverrideRule {
+    /** The lines of `_gates/policy-override.jsonl`. Lines of other ops are ignored. */
+    ledger: {
+        resolutions: readonly GateResolutionRecord[];
+        pending: readonly PendingGateRecord[];
+    };
+    /** The lines of `_gates/policy-override/applied.jsonl`. Absent reads as none. */
+    applied?: readonly AppliedOverrideRecord[];
+    subject: string;
+    /** The plan digest the policy denied. */
+    planDigest: string;
+    /** The ids of the rules that denied it. */
+    rules: readonly string[];
+    /** ISO-8601 now, for whether the standing pending fact has expired. */
+    now?: string;
+}
+/** An override that counts. */
+export interface StandingOverride {
+    subject: string;
+    by: string;
+    at: string;
+    reason: string;
+    rules: string[];
+    /** The plan digest it lets through. */
+    planDigest: string;
+    /** The override digest. */
+    digest: string;
+    sealed: boolean;
+    resolution: GateResolutionRecord;
+}
+export type OverrideDecision = 
+/** An override of this digest counts: the run may apply this plan, after recording {@link appliedOverride}. */
+{
+    status: "overridden";
+    digest: string;
+    override: StandingOverride;
+}
+/**
+ * No override counts. `refusals` says why each override of this digest
+ * does not. `standing` is the unexpired pending fact for this digest, so a
+ * run that finds one records no other. `spent` is the newest override of
+ * another digest a run already applied under.
+ */
+ | {
+    status: "none";
+    digest: string;
+    refusals: string[];
+    standing?: OverridePendingRecord;
+    spent?: {
+        digest: string;
+        by: string;
+        at: string;
+    };
+}
+/** An override counts for another digest and was never applied: the plan or its rules changed after it was written. */
+ | {
+    status: "moved";
+    digest: string;
+    by: string;
+    was: string | undefined;
+    refusals: string[];
+    standing?: OverridePendingRecord;
+};
+/**
+ * Decide one denied plan against the override ledger, as `decideGateApproval`
+ * decides a gate: a line counts only when it is an override of this subject
+ * newer than the subject's newest pending fact, names this digest, passes
+ * {@link overrideRefusal}, and is not spent (an applied record of its digest
+ * made at or after it). The newest counting line wins.
+ *
+ * Decide before recording a denial: an override written after an expired
+ * pending fact still counts, and a run that records a fresh fact first would
+ * make it older than the anchor.
+ */
+export declare function decideOverride(input: OverrideInput): OverrideDecision;
+/** The applied record a run appends before it applies under `override`, which spends it. Appending it is the caller's. */
+export declare function appliedOverride(override: StandingOverride, at: {
+    timestamp: string;
+    runId?: string;
+    commit?: string;
+}): AppliedOverrideRecord;
+/**
+ * The applied records as applies for the audit reader
+ * (`@intentius/chant/lifecycle/gate-audit`), each citing the override it
+ * spent, so the trail shows an `override-spent` entry for it and a gap when
+ * the ledger holds no such override. A product that records its applies
+ * elsewhere cites the override on its own apply instead.
+ */
+export declare function overrideAuditApplies(applied: readonly AppliedOverrideRecord[], path?: string): GateAuditApply[];
+//# sourceMappingURL=override-gate.d.ts.map

package/dist/override-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"override-gate.d.ts","sourceRoot":"","sources":["../src/override-gate.ts"],"names":[],"mappings":"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"}

package/dist/pr-forge.d.ts

@@ -1,20 +1,29 @@
 /**
- * What the pull-request loop (#3183) asks of a forge: keep one note on the
- * pull request up to date, set a commit status per stage, list who approved
- * the pull request, and find the pull request that merged a commit.
+ * What chant and the products built on it ask of a forge: keep one comment
+ * (a merge request note on GitLab) on a pull request up to date, set a commit
+ * status, keep one tracking issue in the repository, list who approved a pull
+ * request, and find the pull request that merged a commit.
  *
- * GitHub and Forgejo speak the same REST shapes for the first three, at
+ * The pull-request loop (#3183) uses the note, the status and the review
+ * calls. `reconcilePr`'s `comment` and `issue` finding modes post through the
+ * same clients (#3757), so a finding needs no `gh` on the runner. terragucci
+ * and SQL Yodeler post their own notes, statuses and drift issues through
+ * them too (#3759): bodies stay with each product, the finding by marker and
+ * the forge's REST shapes live here.
+ *
+ * GitHub and Forgejo speak the same REST shapes for most of this, at
  * different base URLs (`$GITHUB_API_URL` is right on both, #2305); they part
- * on the commit-to-pull-request lookup and on review states. GitLab has its
- * own API for all four. Each client takes a `fetch`, so the tests drive them
- * with a recording fake and no network.
+ * on the commit-to-pull-request lookup, on review states and on page size.
+ * GitLab has its own API for all of it. Each client takes a `fetch`, so the
+ * tests drive them with a recording fake and no network.
  *
  * A reviewer is named the way #3163 names a person: `github:<login>`,
  * `gitlab:<login>`, or `<forge>@<host>:<login>` off the forge's default host.
  * The apply compares that string with the approval's `resolvedBy`.
  *
  * Like `./pr-loop.ts`, this bundles without the TypeScript toolchain (#3421):
- * it imports nothing.
+ * it imports nothing but `node:fs`, to read a CI job's event payload.
+ * `./pr-forge-bundle.test.ts` holds it to that.
  */
 export type ForgeKind = "github" | "gitlab" | "forgejo";
 export declare const FORGE_KINDS: readonly ForgeKind[];
@@ -29,12 +38,67 @@ export type ForgeFetch = (url: string, init: {
     text(): Promise<string>;
 }>;
 export interface ForgeStatus {
-    /** `chant/plan` or `chant/apply`. */
+    /** The status's name, such as `chant/plan` or `terragucci/plan`. */
     context: string;
     state: "pending" | "success" | "failure";
+    /** Cut to what the forge keeps: 140 characters on GitHub and Forgejo, 255 on GitLab. */
     description: string;
     /** The pipeline run, linked from the status. */
     url?: string;
+    /** GitLab only: the pipeline the status belongs to. */
+    pipelineId?: number;
+}
+/**
+ * How a comment or an issue is told to be the caller's own. By default the
+ * body starts with the marker, chant's recipe since #2291, and anyone may
+ * have written it.
+ */
+export interface MarkerMatch {
+    /** `prefix` (the default): the body starts with the marker. `anywhere`: the body carries it. */
+    match?: "prefix" | "anywhere";
+    /**
+     * Only a comment or issue written by this login counts: `user.login` on
+     * GitHub and Forgejo, `author.username` on GitLab, compared without case.
+     * A merge request's author can write a note carrying any marker, so a
+     * product that reads its own notes back names its bot here.
+     */
+    author?: string;
+}
+/** What {@link PrForge.upsertComment} did. */
+export interface CommentResult {
+    action: "created" | "updated" | "unchanged";
+    /** The comment's or note's id. */
+    id: number;
+    /** Its web URL, when the forge's answer carries one (GitHub and Forgejo do; a GitLab note does not). */
+    url?: string;
+}
+/** A finding to keep in a tracking issue. `body` carries the marker. */
+export interface IssueFinding {
+    title: string;
+    body: string;
+}
+export interface TrackIssueOptions extends MarkerMatch {
+    /**
+     * When the finding has cleared (`null`), close the open issue, after
+     * {@link clearComment} when one is given. Off by default: `reconcilePr`'s
+     * `issue` mode never closes an issue, and a closed one is never reopened,
+     * so the next finding opens a fresh issue.
+     */
+    closeOnClear?: boolean;
+    /** Posted on the issue before it is closed. */
+    clearComment?: string;
+}
+/** What {@link PrForge.trackIssue} did. */
+export interface IssueResult {
+    /**
+     * `opened`, `updated`, or `unchanged` (title and body already current) for
+     * a finding; `closed`, `left` (open, `closeOnClear` off) or `none` (no open
+     * issue) for a cleared one.
+     */
+    action: "opened" | "updated" | "unchanged" | "closed" | "left" | "none";
+    /** The issue's number (GitHub, Forgejo) or iid (GitLab). */
+    number?: number;
+    url?: string;
 }
 export interface PrForge {
     kind: ForgeKind;
@@ -44,14 +108,43 @@ export interface PrForge {
     runUrl?: string;
     /** How #3163 names `login` on this forge. */
     principalOf(login: string): string;
-    /** Update the note on `pr` whose body starts with `marker`, or add one. */
-    upsertNote(pr: number, marker: string, body: string): Promise<void>;
+    /**
+     * Keep one comment on pull request `pr` (one note on merge request `pr`):
+     * the one {@link MarkerMatch} finds is updated, unless its body is already
+     * `body`, or one is added. `body` must carry the marker the same way, or
+     * the next run could not find it; that is refused before any call. Every
+     * page of comments is read, and GitLab's system notes are skipped. When
+     * several match, the oldest is kept.
+     */
+    upsertComment(pr: number, marker: string, body: string, opts?: MarkerMatch): Promise<CommentResult>;
+    /**
+     * {@link upsertComment} by prefix, without the body check, resolving to the
+     * comment's web URL. The pull-request loop's form.
+     */
+    upsertNote(pr: number, marker: string, body: string): Promise<string | undefined>;
     setStatus(sha: string, status: ForgeStatus): Promise<void>;
+    /**
+     * Keep one OPEN tracking issue for `marker` in line with `finding`: open
+     * it, update its title and body, or, when `finding` is `null` and
+     * `closeOnClear` is set, close it with a comment. Only open issues are
+     * read, so an issue closed by hand stays closed. Pull requests are never
+     * taken for issues. When several match, the oldest is kept.
+     */
+    trackIssue(marker: string, finding: IssueFinding | null, opts?: TrackIssueOptions): Promise<IssueResult>;
+    /**
+     * {@link trackIssue} by prefix for a finding, without the body check,
+     * resolving to the issue's web URL. `reconcilePr`'s `issue` mode's form.
+     */
+    upsertIssue(marker: string, title: string, body: string): Promise<string | undefined>;
     /** Logins whose standing review approves `pr`. */
     approvers(pr: number): Promise<string[]>;
     /** The merged pull request that produced `sha`, or null. */
     pullRequestFor(sha: string): Promise<number | null>;
 }
+/** A GitHub or Forgejo client. */
+export type GithubShapedForge = PrForge & {
+    kind: "github" | "forgejo";
+};
 /** Thrown when a forge answers a call with an error status. */
 export declare class ForgeApiError extends Error {
     readonly method: string;
@@ -73,33 +166,119 @@ export interface GithubForgeOptions {
     fetch?: ForgeFetch;
 }
 /** A GitHub client (github.com or GitHub Enterprise Server). */
-export declare function githubForge(opts: GithubForgeOptions): PrForge;
+export declare function githubForge(opts: GithubForgeOptions): GithubShapedForge;
 /** A Forgejo (or Gitea) client. `host` is required: Forgejo has no default host. */
 export declare function forgejoForge(opts: GithubForgeOptions & {
     host: string;
-}): PrForge;
+}): GithubShapedForge;
 export interface GitlabForgeOptions {
     /** `$CI_API_V4_URL`. */
     apiBase: string;
     /** `$CI_PROJECT_ID`, or the URL-encoded path. */
     project: string;
     token: string;
+    /**
+     * The header the token goes in: `PRIVATE-TOKEN` (the default) for an
+     * access token, `JOB-TOKEN` for `CI_JOB_TOKEN`. One in the other's header
+     * is a 401.
+     */
+    tokenHeader?: "PRIVATE-TOKEN" | "JOB-TOKEN";
     /** Default gitlab.com. */
     host?: string;
     runUrl?: string;
     fetch?: ForgeFetch;
 }
-/** A GitLab client. The token needs the `api` scope: a job token cannot write merge-request notes. */
+/**
+ * A GitLab client. Writing notes needs an access token with the `api` scope
+ * on most instances: the job token reaches only the endpoints the instance's
+ * job-token allowlist names.
+ */
 export declare function gitlabForge(opts: GitlabForgeOptions): PrForge;
 /** Thrown when the environment lacks what a forge client needs. */
 export declare class ForgeEnvironmentError extends Error {
-    constructor(kind: ForgeKind, missing: string[]);
+    readonly kind: ForgeKind | undefined;
+    readonly missing: string[];
+    /**
+     * @param kind The forge, or undefined when the environment does not say which.
+     * @param missing What is missing, each naming the variable to set.
+     */
+    constructor(kind: ForgeKind | undefined, missing: string[]);
 }
 /**
- * A client for `kind` from the CI job's environment. The token is
- * `CHANT_FORGE_TOKEN` when set, else the forge's own: `GITHUB_TOKEN` (also
- * set on Forgejo Actions) or `GITLAB_TOKEN`. GitLab's `CI_JOB_TOKEN` cannot
- * write notes, so a GitLab pipeline names a project access token.
+ * A client for `kind` from the CI job's environment, as the pull-request
+ * loop reads it. The token is `CHANT_FORGE_TOKEN` when set, else the forge's
+ * own: `GITHUB_TOKEN` (also set on Forgejo Actions) or `GITLAB_TOKEN`.
+ * GitLab's `CI_JOB_TOKEN` cannot write notes, so a GitLab pipeline names a
+ * project access token. {@link forgeTargetFromEnv} is the general reading,
+ * with the finding modes' token order.
  */
 export declare function forgeFromEnv(kind: ForgeKind, env?: Record<string, string | undefined>, fetchImpl?: ForgeFetch): PrForge;
+type Env = Record<string, string | undefined>;
+/**
+ * The forge a CI job runs on, from its environment, or undefined outside a
+ * GitHub Actions, GitLab CI or Forgejo Actions job. Forgejo is told apart by
+ * `FORGEJO_ACTIONS` or `GITEA_ACTIONS`, or by a GitHub-style job whose
+ * `GITHUB_API_URL` ends in `/api/v1`, which GitHub never serves.
+ */
+export declare function detectForge(env?: Env): ForgeKind | undefined;
+/** Where a CI job posts: the forge, the repository, the token, and the pull request and commit when there are ones. */
+export interface ForgeTarget {
+    kind: ForgeKind;
+    /** The REST base: `https://api.github.com`, `<host>/api/v3`, `<host>/api/v1`, or `<host>/api/v4`. */
+    apiBase: string;
+    /** `owner/name` on GitHub and Forgejo; the project id or path on GitLab. */
+    repo: string;
+    /** Lower-cased. */
+    host: string;
+    token: string;
+    /** The variable the token came from, for messages. Never the token itself. */
+    tokenSource: string;
+    /** GitLab: `JOB-TOKEN` when the token is `CI_JOB_TOKEN`, else `PRIVATE-TOKEN`. */
+    tokenHeader?: "PRIVATE-TOKEN" | "JOB-TOKEN";
+    /** The pull request's number, or the merge request's iid. */
+    pr?: number;
+    /** The commit a status belongs on: the pull request's head when the event names it. */
+    sha?: string;
+    /** The run, to link from a status. */
+    runUrl?: string;
+}
+export interface ForgeTargetOptions {
+    /** The forge, in place of {@link detectForge}. */
+    kind?: ForgeKind;
+    /** Read the token from this variable only, in place of the default order. */
+    tokenEnv?: string;
+    /** Refuse an environment with no pull or merge request. Default false. */
+    requirePr?: boolean;
+    /** Reads the event payload `GITHUB_EVENT_PATH` names. Default `node:fs`. */
+    readFile?: (path: string) => string;
+}
+/**
+ * The token order guide/ops documents for the finding modes (#2291, #2256):
+ * a chant-specific variable first, for posting to an instance other than the
+ * one the job runs on, then what the job already carries.
+ */
+export declare const FORGE_TOKEN_ORDER: Record<ForgeKind, readonly string[]>;
+/**
+ * Where a CI job posts, read from its environment: the forge
+ * ({@link detectForge} unless `kind` is given), the repository, the REST
+ * base, the host, the token, and the pull request and its head commit when
+ * the run has them. Throws {@link ForgeEnvironmentError} naming every
+ * missing piece.
+ *
+ * - GitHub Actions: `GITHUB_REPOSITORY`, `GITHUB_API_URL` (default
+ *   `https://api.github.com`), `GITHUB_SERVER_URL`; the pull request from
+ *   the event payload at `GITHUB_EVENT_PATH` or `refs/pull/<n>/` in
+ *   `GITHUB_REF`, its head from the payload, else `GITHUB_SHA`.
+ * - Forgejo Actions: the same, with `FORGEJO_*` read before `GITHUB_*`,
+ *   and the REST base `<server>/api/v1` when no API URL is set.
+ * - GitLab CI: `CI_API_V4_URL` (or `CI_SERVER_URL/api/v4`), the merge
+ *   request's project before the pipeline's (a fork's merge request runs in
+ *   the fork), `CI_MERGE_REQUEST_IID`, `CI_COMMIT_SHA`, `CI_PIPELINE_URL`.
+ *
+ * The token is read in {@link FORGE_TOKEN_ORDER}, or from `tokenEnv` alone.
+ */
+export declare function forgeTargetFromEnv(env?: Env, opts?: ForgeTargetOptions): ForgeTarget;
+/** The client for a {@link ForgeTarget}, from {@link forgeTargetFromEnv} or built by hand. */
+export declare function forgeClient(target: ForgeTarget, fetchImpl?: ForgeFetch): PrForge;
+export {};
 //# sourceMappingURL=pr-forge.d.ts.map

package/dist/pr-forge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pr-forge.d.ts","sourceRoot":"","sources":["../src/pr-forge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pr-forge.d.ts","sourceRoot":"","sources":["../src/pr-forge.ts"],"names":[],"mappings":"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"}

package/dist/workspace/status-gates.d.ts

@@ -16,6 +16,7 @@
  * gate in its environment is the anchor, only approvals recorded since it and
  * for its plan count, and a gate with an `approval` block counts them with
  * `tallyGateApprovals`, as `describeApprovalProgress` does after an approve.
+ * Its human quorum reaches back to `humanQuorumSince` (#3206), as a run's does.
  */
 import { type GateApprovalRule } from "../op/gate.js";
 /** Why a member's gates can't be listed. Closed: a new code is a contract change. */

package/dist/workspace/status-gates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status-gates.d.ts","sourceRoot":"","sources":["../../src/workspace/status-gates.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"status-gates.d.ts","sourceRoot":"","sources":["../../src/workspace/status-gates.ts"],"names":[],"mappings":"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"}

package/dist/workspace/trust/gate-seal.d.ts

@@ -0,0 +1,96 @@
+/**
+ * A gate approval's seal (#3163, ws-080), checked with node:crypto (#3763).
+ *
+ * `chant approve --sign` seals an approval with `ssh-keygen -Y sign` in the
+ * `chant-gate` namespace, over {@link gateSealPayload}. Signing shells to
+ * ssh-keygen; checking does not. This module checks a seal with node:crypto
+ * and no zod, and `checkGateSeal` (`./seal.ts`) and `sealedApprovalRule` use
+ * it, so an apply job needs no ssh-keygen. A tool that decides a gate from one bundled file
+ * (terragucci's apply job) runs the same rule: `@intentius/chant/gate-decision`
+ * exports it.
+ *
+ * An SSHSIG (OpenSSH's PROTOCOL.sshsig) holds the public key, the namespace,
+ * the hash algorithm and the signature over `"SSHSIG"`, the namespace, the
+ * reserved field, the algorithm and the message's hash. Ed25519, ECDSA (P-256,
+ * P-384, P-521), RSA with SHA-2, and the security-key forms of Ed25519 and
+ * P-256 verify, with the touch flag required, as ssh-keygen requires it for a
+ * signers line with no `no-touch-required` option (which the signers parser
+ * does not accept). An RSA signature over SHA-1 does not verify.
+ */
+import type { Signer } from "./trust-files.js";
+/**
+ * The ssh signature namespace of a gate approval's seal (#3163, ws-080), so a
+ * verdict, record or commit signature can't stand in for one.
+ */
+export declare const GATE_SEAL_NAMESPACE = "chant-gate";
+/** The gate approval a seal covers (#3163): the fields of a gate resolution line that say what was approved, by whom and when. */
+export interface SealedGateApproval {
+    op: string;
+    gate: string;
+    environment?: string;
+    planDigest?: string;
+    resolvedBy: string;
+    /** Who relayed the approval for `resolvedBy` (#3402), when someone did. */
+    relayedBy?: string;
+    timestamp: string;
+    seal?: unknown;
+}
+/**
+ * The bytes a gate approval's seal signs (#3163): the op (or component), the
+ * gate, the environment, the plan digest, the approver and the time, joined
+ * by LF with no final newline. An approval that binds no environment or plan
+ * signs an empty line for it. A relayed approval (#3402) signs a seventh line,
+ * `relayed-by <principal>`, so the relay can't be added, changed or removed
+ * after sealing; an approval nobody relayed signs the six lines it always did,
+ * so seals made before #3402 still verify.
+ */
+export declare function gateSealPayload(a: SealedGateApproval): Buffer;
+/** `SHA256:<base64>`, the fingerprint ssh-keygen prints for a public key blob. */
+export declare function sshKeyFingerprint(blob: Buffer): string;
+/** What {@link verifySshSignatureWith} found. */
+export type SshSignatureCheck = {
+    ok: true;
+    key: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Whether `armored`, an SSHSIG as `ssh-keygen -Y sign` writes it, signs
+ * `message` in `namespace` with one of `keys` (public key blobs, ssh wire
+ * format). Never throws. On success, `key` is the signing key's fingerprint.
+ */
+export declare function verifySshSignatureWith(armored: string, message: Buffer, namespace: string, keys: readonly Buffer[]): SshSignatureCheck;
+/**
+ * The key blob an armored SSHSIG carries, or null when it is not one. For
+ * `ssh-keygen -Y check-novalidate`'s question, whether the signature is
+ * intact whoever's key it is: verify against this key.
+ */
+export declare function sshSignatureKey(armored: string): Buffer | null;
+/**
+ * The signers a sealed gate is judged by, read at base. chant's own
+ * `TrustPolicy` (`./policy.ts`) is one; `gateSignersAt` in
+ * `@intentius/chant/gate-decision` reads one without zod.
+ */
+export interface GateSigners {
+    /** The commit the signers were read at, or null when there is no base. */
+    base: string | null;
+    /** The signers path used. */
+    signersPath: string;
+    /** Whether a signers file exists at base. False: no seal verifies, so a sealed gate passes nothing. */
+    active: boolean;
+    signers: Signer[];
+    /** Why the trust config could not be read, when it could not. `active` is false then. */
+    problems: string[];
+}
+/** Whether ssh-keygen's `namespaces="..."` pattern list admits `namespace`: a `*`/`?` pattern matches, and a `!` pattern that matches refuses. */
+export declare function namespaceAllowed(list: string | undefined, namespace: string): boolean;
+/**
+ * Why this approval does not count toward a sealed gate, or null when it
+ * does: its seal verifies, for the approver it names, against a key `signers`
+ * lists for that approver in the `chant-gate` namespace. With no signers file
+ * at base, nothing counts. The same rule as `sealedApprovalRule` in
+ * `../../op/gate-review.ts`, which checks with ssh-keygen.
+ */
+export declare function gateSealRefusal(signers: GateSigners, a: SealedGateApproval): string | null;
+//# sourceMappingURL=gate-seal.d.ts.map