@openvtc/trust-tasks 0.20.7 → 0.21.0

package/src/git-ns/right/break-glass/0.1/payload.ts

@@ -0,0 +1,443 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/git-ns/right/break-glass/0.1/payload.schema.json
+ */
+
+import type { BreakGlass, Did_GitNsV0_3 as Did, ElevatedRight, Ext, Resource, Right, RightRecord_GitNsV0_4 as RightRecord } from "../../../../_shared/components.js";
+
+
+/**
+ * The actor records an elevated git right for themselves — one they already have the authority to grant, but which separation of duties forbids them granting to themselves through git-ns/right/grant — with a mandatory justification. The right takes effect at once, never expires on its own, and is flagged as break-glass, and shown to every other administrator, until another administrator ratifies it with git-ns/right/ratify or anyone entitled revokes it.
+ */
+export interface GitNamespacesBreakGlassPayload {
+  /**
+   * The elevated right the actor records for themselves. The other two rights need no break-glass: git-ns/right/grant lets anyone with authority over them grant them to themselves.
+   */
+  right: ElevatedRight;
+  /**
+   * Where the right applies: the namespace resource for `git.ns.admin` and `git.repo.create`, a repository resource for `git.repo.own`.
+   */
+  resource: Resource;
+  /**
+   * Why nobody else could grant this right now, in the actor's words. Required and never blank. Recorded with the right as `breakGlass.justification`, carried in the audit record and in every notice, and shown to every community administrator, every namespace admin of the namespace and every owner of the resource. Never published to the Trust Registry.
+   */
+  justification: string;
+  ext?: Ext;
+}
+/**
+ * The recorded right, carrying its `breakGlass` flag.
+ */
+export interface GitNamespacesBreakGlassResponsePayload {
+  /**
+   * The recorded right — newly recorded with `breakGlass`, or the live record the actor already held, returned unchanged.
+   */
+  right: RightRecord;
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { BreakGlass, Did, ElevatedRight, Ext, Resource, Right, RightRecord };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/git-ns/right/break-glass/0.1" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = GitNamespacesBreakGlassPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/git-ns/right/break-glass/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = GitNamespacesBreakGlassResponsePayload;
+
+/**
+ * This specification's payload schema, as a value.
+ *
+ * SPEC.md §7.2 item 2 is performed against this. It is shipped as data
+ * rather than only as a `.json` file because TypeScript types are erased
+ * at runtime: without a schema a consumer has nothing to validate, and
+ * every REQUIRED payload member is optional in practice. Cross-file
+ * `$ref`s are already inlined, so it needs no resolver.
+ */
+export const PAYLOAD_SCHEMA = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trusttasks.org/spec/git-ns/right/break-glass/0.1",
+  "title": "Git Namespaces — Break Glass — payload",
+  "description": "The actor records an elevated git right for themselves — one they already have the authority to grant, but which separation of duties forbids them granting to themselves through git-ns/right/grant — with a mandatory justification. The right takes effect at once, never expires on its own, and is flagged as break-glass, and shown to every other administrator, until another administrator ratifies it with git-ns/right/ratify or anyone entitled revokes it.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "right",
+    "resource",
+    "justification"
+  ],
+  "properties": {
+    "right": {
+      "$ref": "#/$defs/ElevatedRight",
+      "description": "The elevated right the actor records for themselves. The other two rights need no break-glass: git-ns/right/grant lets anyone with authority over them grant them to themselves."
+    },
+    "resource": {
+      "$ref": "#/$defs/Resource",
+      "description": "Where the right applies: the namespace resource for `git.ns.admin` and `git.repo.create`, a repository resource for `git.repo.own`."
+    },
+    "justification": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2048,
+      "pattern": "\\S",
+      "description": "Why nobody else could grant this right now, in the actor's words. Required and never blank. Recorded with the right as `breakGlass.justification`, carried in the audit record and in every notice, and shown to every community administrator, every namespace admin of the namespace and every owner of the resource. Never published to the Trust Registry."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext"
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "Git Namespaces — Break Glass — response payload",
+      "description": "The recorded right, carrying its `breakGlass` flag.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "right"
+      ],
+      "properties": {
+        "right": {
+          "$ref": "#/$defs/RightRecord",
+          "description": "The recorded right — newly recorded with `breakGlass`, or the live record the actor already held, returned unchanged."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "Ext": {
+      "title": "Ext",
+      "description": "Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": true,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
+      }
+    },
+    "RightRecord": {
+      "title": "RightRecord",
+      "description": "One recorded right. Implied rights (§4.2 of the rights model: `own` implies `maintain` implies `commit.sign` on the same resource; `ns.admin` implies `repo.create` and `own` across its namespace) are not records and never appear as RightRecords. A record carrying `breakGlass` was given by its subject to themselves through git-ns/right/break-glass; it is a real right, published like any other, and is shown with that flag on every surface that shows the record.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "subject",
+        "right",
+        "resource",
+        "grantedBy",
+        "grantedAt"
+      ],
+      "properties": {
+        "subject": {
+          "$ref": "#/$defs/Did",
+          "description": "Who holds the right. For `git.commit.sign` this is the DID whose commit signatures the CI check accepts."
+        },
+        "right": {
+          "$ref": "#/$defs/Right"
+        },
+        "resource": {
+          "$ref": "#/$defs/Resource"
+        },
+        "grantedBy": {
+          "$ref": "#/$defs/Did",
+          "description": "The actor whose task caused the right: the granter, the creator of a repository (for its first `own`), the adopting admin, the transferring owner, or the binding admin (for the first `git.ns.admin`). The VTC's own DID for a right it derives from its configuration."
+        },
+        "grantedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the right lapses. Absent: no expiry."
+        },
+        "reason": {
+          "type": "string",
+          "maxLength": 1024,
+          "description": "The granter's free-text reason. Disclosed only to holders of `git.repo.own` on the resource and of `git.ns.admin` over it."
+        },
+        "breakGlass": {
+          "$ref": "#/$defs/BreakGlass",
+          "description": "Present exactly when the subject gave themselves this right through git-ns/right/break-glass. Absent for every other record."
+        }
+      }
+    },
+    "BreakGlass": {
+      "title": "BreakGlass",
+      "description": "How a self-granted right came to be, and whether another administrator has since ratified it. A record whose `breakGlass` has no `ratifiedBy` is **unratified**: it is live and published like any other right, it does not count toward the last-owner or last-admin invariants, and any community administrator or namespace admin of its namespace may revoke it. Ratification (git-ns/right/ratify) sets `ratifiedBy` and `ratifiedAt`; from then on the record is an ordinary grant, and `breakGlass` stays as its history. Never published to the Trust Registry.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "by",
+        "at",
+        "justification"
+      ],
+      "properties": {
+        "by": {
+          "$ref": "#/$defs/Did",
+          "description": "Who broke the glass: always the record's `subject`, restated so the flag reads on its own."
+        },
+        "at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the VTC recorded the break-glass."
+        },
+        "justification": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2048,
+          "pattern": "\\S",
+          "description": "The actor's statement of why nobody else could grant this right. Shown to every community administrator, every namespace admin of the namespace and every owner of the resource; kept in the audit record; never published."
+        },
+        "effectiveAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the right takes effect, where the community's policy imposed a delay. Absent: it took effect at `at`. Until this instant the record confers nothing and is not published, and any administrator who may revoke it may do so."
+        },
+        "ratifiedBy": {
+          "$ref": "#/$defs/Did",
+          "description": "The administrator who ratified the record — never its subject. Absent while unratified."
+        },
+        "ratifiedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When it was ratified. Present exactly when `ratifiedBy` is."
+        }
+      }
+    },
+    "Did": {
+      "title": "Did",
+      "description": "A bare DID in the W3C DID Core syntax (§3.1): `did:`, a method name of lowercase letters and digits, `:`, and a method-specific id of colon-separated segments drawn from `A-Z a-z 0-9 . - _` and percent-encoded octets, the last segment non-empty. A DID URL is not a DID: no path, query or fragment (`/`, `?`, `#`), so a verification-method id such as `did:key:z6Mk…#z6Mk…` is refused. Compared by exact string equality — no case folding or percent-decoding. A consumer MUST still treat the value as data: the pattern keeps shell metacharacters, whitespace and quotes out of the wire form, but it does not make a DID safe to splice into a command or markup.",
+      "type": "string",
+      "maxLength": 2048,
+      "pattern": "^did:[a-z0-9]+:(?:(?:[A-Za-z0-9._-]|%[0-9A-Fa-f]{2})*:)*(?:[A-Za-z0-9._-]|%[0-9A-Fa-f]{2})+$"
+    },
+    "Resource": {
+      "title": "Resource",
+      "description": "A forge-qualified resource: `<forge-host>/<owner>` for a namespace, or `<forge-host>/<owner>/<repo>` for one repository, all lowercase — `github.com/acme`, `github.com/acme/widgets`, `codeberg.org/acme`. The forge is never implied: `acme/widgets` alone is not a resource. Containment is by whole segment: `github.com/acme` contains `github.com/acme/widgets` and does not contain `github.com/acme-labs/x` or `codeberg.org/acme/widgets`.",
+      "type": "string",
+      "maxLength": 455,
+      "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+(?:/[a-z0-9_-][a-z0-9._-]{0,99}){1,2}$"
+    },
+    "Right": {
+      "title": "Right",
+      "description": "One of the five git rights. Each string is also the TRQP `action` the VTC publishes the right under in its Trust Registry, so it is carried verbatim. `git.ns.admin` and `git.repo.create` apply to a namespace resource; `git.repo.own` and `git.repo.maintain` to a repository resource; `git.commit.sign` to either.",
+      "type": "string",
+      "enum": [
+        "git.ns.admin",
+        "git.repo.create",
+        "git.repo.own",
+        "git.repo.maintain",
+        "git.commit.sign"
+      ]
+    },
+    "ElevatedRight": {
+      "title": "ElevatedRight",
+      "description": "The three rights that carry authority over other people's rights: `git.ns.admin`, `git.repo.create` (which makes its holder the owner of every repository they create) and `git.repo.own`. Separation of duties applies to these: nobody grants one to themselves through git-ns/right/grant, or records one for themselves through any other task that grants on the actor's own authority. The explicit self-grant is git-ns/right/break-glass. `git.repo.maintain` and `git.commit.sign` are not elevated.",
+      "type": "string",
+      "enum": [
+        "git.ns.admin",
+        "git.repo.create",
+        "git.repo.own"
+      ]
+    }
+  }
+} as const;
+
+/** As {@link PAYLOAD_SCHEMA}, for the success-response variant. */
+export const RESPONSE_PAYLOAD_SCHEMA = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$ref": "#/$defs/Response",
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "Git Namespaces — Break Glass — response payload",
+      "description": "The recorded right, carrying its `breakGlass` flag.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "right"
+      ],
+      "properties": {
+        "right": {
+          "$ref": "#/$defs/RightRecord",
+          "description": "The recorded right — newly recorded with `breakGlass`, or the live record the actor already held, returned unchanged."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "Ext": {
+      "title": "Ext",
+      "description": "Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": true,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
+      }
+    },
+    "RightRecord": {
+      "title": "RightRecord",
+      "description": "One recorded right. Implied rights (§4.2 of the rights model: `own` implies `maintain` implies `commit.sign` on the same resource; `ns.admin` implies `repo.create` and `own` across its namespace) are not records and never appear as RightRecords. A record carrying `breakGlass` was given by its subject to themselves through git-ns/right/break-glass; it is a real right, published like any other, and is shown with that flag on every surface that shows the record.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "subject",
+        "right",
+        "resource",
+        "grantedBy",
+        "grantedAt"
+      ],
+      "properties": {
+        "subject": {
+          "$ref": "#/$defs/Did",
+          "description": "Who holds the right. For `git.commit.sign` this is the DID whose commit signatures the CI check accepts."
+        },
+        "right": {
+          "$ref": "#/$defs/Right"
+        },
+        "resource": {
+          "$ref": "#/$defs/Resource"
+        },
+        "grantedBy": {
+          "$ref": "#/$defs/Did",
+          "description": "The actor whose task caused the right: the granter, the creator of a repository (for its first `own`), the adopting admin, the transferring owner, or the binding admin (for the first `git.ns.admin`). The VTC's own DID for a right it derives from its configuration."
+        },
+        "grantedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the right lapses. Absent: no expiry."
+        },
+        "reason": {
+          "type": "string",
+          "maxLength": 1024,
+          "description": "The granter's free-text reason. Disclosed only to holders of `git.repo.own` on the resource and of `git.ns.admin` over it."
+        },
+        "breakGlass": {
+          "$ref": "#/$defs/BreakGlass",
+          "description": "Present exactly when the subject gave themselves this right through git-ns/right/break-glass. Absent for every other record."
+        }
+      }
+    },
+    "BreakGlass": {
+      "title": "BreakGlass",
+      "description": "How a self-granted right came to be, and whether another administrator has since ratified it. A record whose `breakGlass` has no `ratifiedBy` is **unratified**: it is live and published like any other right, it does not count toward the last-owner or last-admin invariants, and any community administrator or namespace admin of its namespace may revoke it. Ratification (git-ns/right/ratify) sets `ratifiedBy` and `ratifiedAt`; from then on the record is an ordinary grant, and `breakGlass` stays as its history. Never published to the Trust Registry.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "by",
+        "at",
+        "justification"
+      ],
+      "properties": {
+        "by": {
+          "$ref": "#/$defs/Did",
+          "description": "Who broke the glass: always the record's `subject`, restated so the flag reads on its own."
+        },
+        "at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the VTC recorded the break-glass."
+        },
+        "justification": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2048,
+          "pattern": "\\S",
+          "description": "The actor's statement of why nobody else could grant this right. Shown to every community administrator, every namespace admin of the namespace and every owner of the resource; kept in the audit record; never published."
+        },
+        "effectiveAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the right takes effect, where the community's policy imposed a delay. Absent: it took effect at `at`. Until this instant the record confers nothing and is not published, and any administrator who may revoke it may do so."
+        },
+        "ratifiedBy": {
+          "$ref": "#/$defs/Did",
+          "description": "The administrator who ratified the record — never its subject. Absent while unratified."
+        },
+        "ratifiedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When it was ratified. Present exactly when `ratifiedBy` is."
+        }
+      }
+    },
+    "Did": {
+      "title": "Did",
+      "description": "A bare DID in the W3C DID Core syntax (§3.1): `did:`, a method name of lowercase letters and digits, `:`, and a method-specific id of colon-separated segments drawn from `A-Z a-z 0-9 . - _` and percent-encoded octets, the last segment non-empty. A DID URL is not a DID: no path, query or fragment (`/`, `?`, `#`), so a verification-method id such as `did:key:z6Mk…#z6Mk…` is refused. Compared by exact string equality — no case folding or percent-decoding. A consumer MUST still treat the value as data: the pattern keeps shell metacharacters, whitespace and quotes out of the wire form, but it does not make a DID safe to splice into a command or markup.",
+      "type": "string",
+      "maxLength": 2048,
+      "pattern": "^did:[a-z0-9]+:(?:(?:[A-Za-z0-9._-]|%[0-9A-Fa-f]{2})*:)*(?:[A-Za-z0-9._-]|%[0-9A-Fa-f]{2})+$"
+    },
+    "Resource": {
+      "title": "Resource",
+      "description": "A forge-qualified resource: `<forge-host>/<owner>` for a namespace, or `<forge-host>/<owner>/<repo>` for one repository, all lowercase — `github.com/acme`, `github.com/acme/widgets`, `codeberg.org/acme`. The forge is never implied: `acme/widgets` alone is not a resource. Containment is by whole segment: `github.com/acme` contains `github.com/acme/widgets` and does not contain `github.com/acme-labs/x` or `codeberg.org/acme/widgets`.",
+      "type": "string",
+      "maxLength": 455,
+      "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+(?:/[a-z0-9_-][a-z0-9._-]{0,99}){1,2}$"
+    },
+    "Right": {
+      "title": "Right",
+      "description": "One of the five git rights. Each string is also the TRQP `action` the VTC publishes the right under in its Trust Registry, so it is carried verbatim. `git.ns.admin` and `git.repo.create` apply to a namespace resource; `git.repo.own` and `git.repo.maintain` to a repository resource; `git.commit.sign` to either.",
+      "type": "string",
+      "enum": [
+        "git.ns.admin",
+        "git.repo.create",
+        "git.repo.own",
+        "git.repo.maintain",
+        "git.commit.sign"
+      ]
+    },
+    "ElevatedRight": {
+      "title": "ElevatedRight",
+      "description": "The three rights that carry authority over other people's rights: `git.ns.admin`, `git.repo.create` (which makes its holder the owner of every repository they create) and `git.repo.own`. Separation of duties applies to these: nobody grants one to themselves through git-ns/right/grant, or records one for themselves through any other task that grants on the actor's own authority. The explicit self-grant is git-ns/right/break-glass. `git.repo.maintain` and `git.commit.sign` are not elevated.",
+      "type": "string",
+      "enum": [
+        "git.ns.admin",
+        "git.repo.create",
+        "git.repo.own"
+      ]
+    }
+  }
+} as const;
+
+/**
+ * SPEC.md §7.2 policy for the request variant, from this specification's
+ * front matter. Pass to `consumeInbound` — items 5b, 7 and 8 are
+ * per-specification and cannot be derived from the document alone, and
+ * item 2 needs the schema this carries.
+ */
+export const SPEC = {
+  typeUri: TYPE_URI,
+  isBearer: false,
+  isProofRequired: true,
+  isRecipientRequired: true,
+  isIssuedAtRequired: true,
+  payloadSchema: PAYLOAD_SCHEMA,
+} as const;
+
+/**
+ * SPEC.md §7.2 policy for the success-response variant. `isRecipientRequired`
+ * tracks the *issuer* party's requirement because a response swaps the
+ * parties (§7.3 item 5).
+ */
+export const RESPONSE_SPEC = {
+  typeUri: RESPONSE_TYPE_URI,
+  isBearer: false,
+  isProofRequired: true,
+  isRecipientRequired: true,
+  isIssuedAtRequired: true,
+  payloadSchema: RESPONSE_PAYLOAD_SCHEMA,
+} as const;