@opensoftware/contracts 2.5.0 → 2.7.0

package/openapi/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Open Software Factory contracts",
-    "version": "2.5.0",
+    "version": "2.7.0",
     "description": "The shared formats as named models, and the HTTP APIs of the modules. Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
     "license": {
       "name": "Apache-2.0",
@@ -1042,7 +1042,7 @@
             "items": {
               "type": "string"
             },
-            "description": "Paths to skill folders."
+            "description": "The agent's skills: each a path to a skill folder, or a folder of another Git repository at a ref,\n`git+<url>#<ref>:<path>`, which `factory plan` pins in factory.lock (ADR 0146)."
           },
           "secrets": {
             "type": "array",
@@ -1173,6 +1173,11 @@
         ],
         "additionalProperties": false
       },
+      "Base64url32": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9_-]{43}$",
+        "description": "43 characters of base64url without padding: 32 bytes, like a SHA-256 or an Ed25519 public key."
+      },
       "Benchmark": {
         "type": "object",
         "properties": {
@@ -1203,6 +1208,128 @@
         "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))[^\\\\]+$",
         "description": "A path inside the bundle: relative, forward slashes, no \"..\"."
       },
+      "CatalogSkill": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The last segment of the skill's folder."
+          },
+          "description": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The description of its front matter; null without one."
+          },
+          "source": {
+            "$ref": "#/components/schemas/CatalogSkillSource",
+            "description": "Where the skill comes from."
+          },
+          "needs": {
+            "$ref": "#/components/schemas/SkillNeeds",
+            "description": "What it needs, from the `metadata` of its front matter."
+          },
+          "agents": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/CatalogSkillAgent"
+            },
+            "description": "Each agent that uses it, sorted by name."
+          },
+          "files": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The files of its folder, by their path below it, sorted."
+          },
+          "body": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The text of SKILL.md below the line that ends its front matter, all of it without front matter; null without a\nSKILL.md that is UTF-8 text."
+          },
+          "problems": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The problems of its own files as `factory lint` prints them, relative to the folder of factory.yaml, and a folder\nwithout a SKILL.md."
+          }
+        },
+        "required": [
+          "name",
+          "description",
+          "source",
+          "needs",
+          "agents",
+          "files",
+          "body",
+          "problems"
+        ],
+        "description": "One skill, also one that lint refuses: then `problems` names why."
+      },
+      "CatalogSkillAgent": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "secrets": {
+            "type": "object",
+            "properties": {},
+            "unevaluatedProperties": {
+              "$ref": "#/components/schemas/SecretReference"
+            },
+            "description": "The agent's reference whose variable is each secret the skill needs, by the variable."
+          },
+          "lacks": {
+            "$ref": "#/components/schemas/SkillNeeds",
+            "description": "Each needed secret the agent does not declare, and each needed host its sandbox does not allow."
+          }
+        },
+        "required": [
+          "name",
+          "secrets",
+          "lacks"
+        ],
+        "description": "An agent that uses a skill."
+      },
+      "CatalogSkillSource": {
+        "type": "object",
+        "properties": {
+          "folder": {
+            "type": "string",
+            "minLength": 1
+          },
+          "repository": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The URL of the other Git repository, as the entry `git+<url>#<ref>:<path>` names it."
+          },
+          "commit": {
+            "type": "string",
+            "pattern": "^([0-9a-f]{40}|[0-9a-f]{64})$",
+            "description": "The commit of the other repository that factory.lock pins; none while factory.lock has no pin."
+          }
+        },
+        "required": [
+          "folder"
+        ],
+        "description": "A folder of the factory's repository, relative to the folder of factory.yaml, like \"skills/release-notes\"; or, for a\nskill of another Git repository, its folder there with the repository's URL and the commit factory.lock pins\n(ADR 0146)."
+      },
       "CheckName": {
         "type": "string",
         "minLength": 1,
@@ -1513,6 +1640,14 @@
               }
             },
             "description": "The adapters under `providers` that `factory plan --adapters` pinned, per port and adapter name (ADR 0125). A pin\ncounts only while its `range` is the range factory.yaml declares."
+          },
+          "skills": {
+            "type": "object",
+            "properties": {},
+            "unevaluatedProperties": {
+              "$ref": "#/components/schemas/FactoryLockSkillPin"
+            },
+            "description": "The skills of other Git repositories that `factory plan` pinned, by the skill's name (ADR 0146). A pin counts only\nwhile its `source` is the entry factory.yaml declares; the foreman and `factory render` fetch its commit and check\nits hash."
           }
         },
         "required": [
@@ -1599,6 +1734,33 @@
         ],
         "description": "One registry MCP server at its exact version, with the npm package or the remote it starts."
       },
+      "FactoryLockSkillPin": {
+        "type": "object",
+        "properties": {
+          "source": {
+            "type": "string",
+            "pattern": "^git\\+.+#[^:]+:.+$",
+            "description": "The entry of `skills` in factory.yaml that the pin was resolved from, `git+<url>#<ref>:<path>`."
+          },
+          "commit": {
+            "type": "string",
+            "pattern": "^([0-9a-f]{40}|[0-9a-f]{64})$",
+            "description": "The full commit, 40 hexadecimal characters, or 64 in a repository of SHA-256."
+          },
+          "hash": {
+            "type": "string",
+            "pattern": "^h1:[A-Za-z0-9+/]{43}=$",
+            "description": "The hash of the skill folder's files in the form of Go's modules: \"h1:\" and the base64 of a SHA-256."
+          }
+        },
+        "required": [
+          "source",
+          "commit",
+          "hash"
+        ],
+        "description": "One skill of another Git repository at the commit its ref had when `factory plan` pinned it.",
+        "additionalProperties": false
+      },
       "FormatVersion": {
         "type": "integer",
         "minimum": 1,
@@ -2288,6 +2450,125 @@
           "source"
         ]
       },
+      "PersonKey": {
+        "type": "object",
+        "properties": {
+          "kty": {
+            "type": "string",
+            "const": "OKP"
+          },
+          "crv": {
+            "type": "string",
+            "const": "Ed25519"
+          },
+          "alg": {
+            "type": "string",
+            "const": "Ed25519"
+          },
+          "use": {
+            "type": "string",
+            "const": "sig"
+          },
+          "kid": {
+            "$ref": "#/components/schemas/Base64url32",
+            "description": "The key's JWK thumbprint (RFC 7638) with SHA-256; a proof names it in its `kid`."
+          },
+          "x": {
+            "$ref": "#/components/schemas/Base64url32",
+            "description": "The public key."
+          }
+        },
+        "required": [
+          "kty",
+          "crv",
+          "alg",
+          "use",
+          "kid",
+          "x"
+        ],
+        "description": "One Ed25519 public key. Closed: a key with its private part `d` or any other member is invalid.",
+        "additionalProperties": false
+      },
+      "PersonKeys": {
+        "type": "object",
+        "properties": {
+          "keys": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PersonKey"
+            },
+            "minItems": 1
+          }
+        },
+        "required": [
+          "keys"
+        ],
+        "description": "The public keys of an issuer of person proofs (ADR 0151): a JSON Web Key Set (RFC 7517), as the console publishes it\nat `/.well-known/jwks.json`. The first key of the issuer's setting signs; every key here verifies.",
+        "additionalProperties": false
+      },
+      "PersonProof": {
+        "type": "object",
+        "properties": {
+          "iss": {
+            "$ref": "#/components/schemas/Name",
+            "description": "The issuer: \"console\" for the console, or the name a team gives its own tool in the modules' setting."
+          },
+          "sub": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The person, as the module records the actor's `id`: an email in lower case, or the sign-in proxy's value."
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The name to show, recorded as the actor's `displayName`."
+          },
+          "role": {
+            "$ref": "#/components/schemas/AccessRole",
+            "description": "The person's role from the access file at the time of the call."
+          },
+          "aud": {
+            "$ref": "#/components/schemas/Name",
+            "description": "The module the call goes to: \"foreman\", \"intake\" or \"gatekeeper\"."
+          },
+          "iat": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "When it was signed, in seconds since 1970-01-01T00:00:00Z."
+          },
+          "exp": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "When it ends, in seconds since 1970-01-01T00:00:00Z; at most 60 seconds after `iat`."
+          },
+          "method": {
+            "type": "string",
+            "pattern": "^[A-Z]+$",
+            "description": "The request's method in upper case."
+          },
+          "path": {
+            "type": "string",
+            "pattern": "^/[^?#]*$",
+            "description": "The request's path as sent in the request line, without the query."
+          },
+          "bodyDigest": {
+            "$ref": "#/components/schemas/Base64url32",
+            "description": "The SHA-256 of the request's body bytes as sent, in base64url without padding."
+          }
+        },
+        "required": [
+          "iss",
+          "sub",
+          "role",
+          "aud",
+          "iat",
+          "exp",
+          "method",
+          "path",
+          "bodyDigest"
+        ],
+        "description": "The claims of a person proof (ADR 0151): the JSON Web Token that the console signs for one call of a module API in\nthe name of a person, sent in the header `OSF-Person`, signed with `alg` \"Ed25519\" and `typ` \"osf-person+jwt\". It is\nbound to one module, one request and 30 seconds. Open: a module ignores a claim it does not know."
+      },
       "PrClosed": {
         "type": "object",
         "properties": {
@@ -3707,6 +3988,53 @@
         "type": "string",
         "pattern": "^[0-9a-f]{64}$"
       },
+      "SkillCatalog": {
+        "type": "object",
+        "properties": {
+          "skills": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/CatalogSkill"
+            }
+          }
+        },
+        "required": [
+          "skills"
+        ],
+        "description": "What `factory skills` of factory-spec prints (ADR 0141, ADR 0143): every skill the factory's agents use, read with\nthe rules of `factory lint` (ADR 0140), sorted by name. The console reads it for its pages `/skills` and\n`/skills/<name>`, so it never parses a SKILL.md itself."
+      },
+      "SkillHost": {
+        "type": "string",
+        "pattern": "^[a-z0-9-]+(\\.[a-z0-9-]+)*$",
+        "description": "A host as an entry of `sandbox.egress`, like \"api.linear.app\"."
+      },
+      "SkillNeeds": {
+        "type": "object",
+        "properties": {
+          "secrets": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SkillSecretName"
+            }
+          },
+          "hosts": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SkillHost"
+            }
+          }
+        },
+        "required": [
+          "secrets",
+          "hosts"
+        ],
+        "description": "The secrets a skill needs, by the variable that holds each in a sandbox, and the hosts it reaches (ADR 0140)."
+      },
+      "SkillSecretName": {
+        "type": "string",
+        "pattern": "^[A-Z0-9_]+$",
+        "description": "The variable of a secret in a sandbox (ADR 0068), like \"LINEAR_TOKEN\"."
+      },
       "Stage": {
         "type": "object",
         "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensoftware/contracts",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "The shared formats of the open software factory: JSON Schemas, TypeScript types and the osf-contracts CLI.",
   "license": "Apache-2.0",
   "repository": {
@@ -44,7 +44,7 @@
     "@typespec/openapi": "1.17.0",
     "@typespec/openapi3": "1.17.0",
     "openapi-typescript": "7.13.0",
-    "@opensoftware/testkit": "0.37.0"
+    "@opensoftware/testkit": "0.39.0"
   },
   "scripts": {
     "build": "node scripts/build.ts",

package/person-keys/person-keys.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/sesigl/open-software-factory/main/contracts/person-keys/person-keys.schema.json",
+  "title": "PersonKeys",
+  "$comment": "Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
+  "type": "object",
+  "properties": {
+    "keys": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "kty": {
+            "type": "string",
+            "const": "OKP"
+          },
+          "crv": {
+            "type": "string",
+            "const": "Ed25519"
+          },
+          "alg": {
+            "type": "string",
+            "const": "Ed25519"
+          },
+          "use": {
+            "type": "string",
+            "const": "sig"
+          },
+          "kid": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_-]{43}$",
+            "description": "The key's JWK thumbprint (RFC 7638) with SHA-256; a proof names it in its `kid`."
+          },
+          "x": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_-]{43}$",
+            "description": "The public key."
+          }
+        },
+        "required": [
+          "kty",
+          "crv",
+          "alg",
+          "use",
+          "kid",
+          "x"
+        ],
+        "description": "One Ed25519 public key. Closed: a key with its private part `d` or any other member is invalid.",
+        "additionalProperties": false
+      },
+      "minItems": 1
+    }
+  },
+  "required": [
+    "keys"
+  ],
+  "description": "The public keys of an issuer of person proofs (ADR 0151): a JSON Web Key Set (RFC 7517), as the console publishes it\nat `/.well-known/jwks.json`. The first key of the issuer's setting signs; every key here verifies.",
+  "additionalProperties": false
+}

package/person-proof/person-proof.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/sesigl/open-software-factory/main/contracts/person-proof/person-proof.schema.json",
+  "title": "PersonProof",
+  "$comment": "Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
+  "type": "object",
+  "properties": {
+    "iss": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{0,62}$",
+      "description": "The issuer: \"console\" for the console, or the name a team gives its own tool in the modules' setting."
+    },
+    "sub": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The person, as the module records the actor's `id`: an email in lower case, or the sign-in proxy's value."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The name to show, recorded as the actor's `displayName`."
+    },
+    "role": {
+      "type": "string",
+      "enum": [
+        "member",
+        "factory-engineer",
+        "admin"
+      ],
+      "description": "The person's role from the access file at the time of the call."
+    },
+    "aud": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{0,62}$",
+      "description": "The module the call goes to: \"foreman\", \"intake\" or \"gatekeeper\"."
+    },
+    "iat": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "When it was signed, in seconds since 1970-01-01T00:00:00Z."
+    },
+    "exp": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "When it ends, in seconds since 1970-01-01T00:00:00Z; at most 60 seconds after `iat`."
+    },
+    "method": {
+      "type": "string",
+      "pattern": "^[A-Z]+$",
+      "description": "The request's method in upper case."
+    },
+    "path": {
+      "type": "string",
+      "pattern": "^/[^?#]*$",
+      "description": "The request's path as sent in the request line, without the query."
+    },
+    "bodyDigest": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{43}$",
+      "description": "The SHA-256 of the request's body bytes as sent, in base64url without padding."
+    }
+  },
+  "required": [
+    "iss",
+    "sub",
+    "role",
+    "aud",
+    "iat",
+    "exp",
+    "method",
+    "path",
+    "bodyDigest"
+  ],
+  "description": "The claims of a person proof (ADR 0151): the JSON Web Token that the console signs for one call of a module API in\nthe name of a person, sent in the header `OSF-Person`, signed with `alg` \"Ed25519\" and `typ` \"osf-person+jwt\". It is\nbound to one module, one request and 30 seconds. Open: a module ignores a claim it does not know."
+}