fhirsmith 0.18.1 → 1.0.0

package/packages/openapi.yaml

@@ -164,6 +164,74 @@ paths:
         '400': { $ref: '#/components/responses/BadRequest' }
         '500': { $ref: '#/components/responses/ServerError' }
 
+  /-/fhir/v1/signatures/{spec}:
+    get:
+      tags: [registry]
+      operationId: getPublisherSignature
+      summary: The publisher's signature of a package version
+      description: |
+        The signature a package's publisher made of it (its `{package}.tgz.sigstore.json`,
+        linked from the publisher's feed by `fhir:signature`), exactly as this registry fetched
+        and checked it. It is a Sigstore bundle: an ECDSA P-256 signature of an in-toto
+        statement naming the package (`pkg:npm/{name}@{version}`) and the sha512 of the
+        `.tgz`. The keys a feed may sign with are listed in the FHIR package registry's
+        `package-feeds.json`; a client can check the signature against them itself.
+
+        Each version's `dist.fhir-signature` in the package document links this, with what
+        the registry made of it (`confirmed` or `rejected`). It isn't `dist.attestations`:
+        npm would try to verify it as a Sigstore attestation, which it isn't (it has no
+        transparency log entry, and the publisher's key isn't the registry's).
+      parameters:
+        - name: spec
+          in: path
+          required: true
+          description: '`{name}@{version}`, as npm writes it (a scope''s `/` escaped).'
+          schema: { type: string }
+          example: hl7.fhir.uv.ips@2.0.0
+      responses:
+        '200':
+          description: The signature bundle, as fetched
+          content:
+            application/json:
+              schema: { type: object }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '404':
+          description: No signature is held for this package version
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+        '500': { $ref: '#/components/responses/ServerError' }
+
+  /-/npm/v1/keys:
+    get:
+      tags: [registry]
+      operationId: getSigningKeys
+      summary: The registry's signing keys (npm registry signatures)
+      description: |
+        The public keys this registry signs package versions with, in the npm registry's
+        format, so `npm audit signatures` can check packages installed from here. Each
+        version's `dist.signatures` holds the signature of `{id}@{version}:{dist.integrity}`
+        (ECDSA P-256, SHA-256, base64 DER).
+
+        A signature says this registry served that tarball. It is the registry's, not the
+        publisher's: this registry signs every version it holds, wherever it was crawled
+        from.
+
+        A 404 means the registry doesn't sign, which npm accepts. It is also the answer
+        while the registry is still signing versions it stored before it signed, since
+        npm reports an unsigned version from a registry with keys as an error.
+      responses:
+        '200':
+          description: The keys
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SigningKeys' }
+        '404':
+          description: This registry doesn't sign packages (or hasn't finished signing them)
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+
   /updates:
     get:
       tags: [search]
@@ -254,6 +322,9 @@ paths:
 
         With `Accept: text/html` and no parameters, this is a form for running the checks.
 
+        If the registry lists signing keys (`/-/npm/v1/keys`), it also checks that every
+        version of the package is signed with one of them, as `npm audit signatures` does.
+
         A run makes about ten requests, each limited in time and size, and only to public
         addresses. Runs are rate limited per client address, and the server runs only a
         few at once. A server can turn the check off (`npmCheck.enabled` in its
@@ -312,6 +383,103 @@ paths:
               schema: { $ref: '#/components/schemas/Error' }
         '500': { $ref: '#/components/responses/ServerError' }
 
+  /feed-check:
+    get:
+      tags: [tools]
+      operationId: checkPackageFeed
+      summary: Check a package feed the way the crawler reads it
+      description: |
+        Reads a package feed (RSS, as listed in the FHIR package registry's package-feeds.json)
+        the way this registry's crawler does, and reports what it finds, without storing
+        anything: for each item, its package (downloaded, unpacked and checked as the crawler
+        checks it before storing), whether the registry's package-restrictions allow it from
+        this feed, its signature (against the keys the registry lists for the feed), and
+        whether this registry already holds it. Next pages are followed, up to an item limit.
+
+        A check runs in the background: this starts one and returns `202` with its id
+        (`303` to its report page, for a browser). Poll `/feed-check/{run}` for the report.
+        With `Accept: text/html` and no `url`, this is a form.
+
+        Every request a check makes goes only to public addresses. Only one check runs at a
+        time, across all users. A server can turn the check off (`feedCheck.enabled`), and then
+        this returns 404.
+      parameters:
+        - name: url
+          in: query
+          required: true
+          description: The feed's URL.
+          schema:
+            type: string
+            maxLength: 500
+            pattern: '^https?:\/\/[^\s<>"''`]+$'
+          example: https://hl7.org/fhir/package-feed.xml
+        - name: signing
+          in: query
+          required: false
+          description: |
+            The feed's signing keys, as JSON: its `signing` block as it would be in
+            package-feeds.json (`{"required": false, "keys": [{"keyid": ..., "key": ..., "expires": null}]}`),
+            or the feed's whole entry. Signatures are checked against these instead of the keys
+            the registry lists for the feed.
+          schema:
+            type: string
+            maxLength: 5000
+            pattern: '^[^<>`]*$'
+      responses:
+        '202':
+          description: The check has started
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id: { type: string }
+                  state: { type: string, enum: [running] }
+                  report: { type: string, description: Where to get the report }
+        '303': { description: 'For a browser: the report page' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '404':
+          description: The check is turned off on this server
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+        '503':
+          description: A check is already running (one at a time); try again shortly
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+        '500': { $ref: '#/components/responses/ServerError' }
+
+  /feed-check/{run}:
+    get:
+      tags: [tools]
+      operationId: getFeedCheck
+      summary: A feed check's report
+      description: |
+        The report of a check started with `/feed-check`: `state` is `running` (the report so
+        far), `done` or `failed`. Reports are kept for a while (an hour, by default) after the
+        check finishes. A browser gets a page that reloads until the check is done.
+      parameters:
+        - name: run
+          in: path
+          required: true
+          description: The check's id, as `/feed-check` returned it.
+          schema: { type: string }
+      responses:
+        '200':
+          description: The check and its report
+          content:
+            application/json:
+              schema: { type: object }
+            text/html:
+              schema: { type: string }
+        '404':
+          description: No such check (or its report has been discarded)
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+        '500': { $ref: '#/components/responses/ServerError' }
+
   /{id}:
     get:
       tags: [registry]
@@ -683,8 +851,46 @@ components:
           type: object
           required: [tarball]
           properties:
-            shasum: { type: string }
+            shasum: { type: string, description: sha1 of the tarball, hex }
+            integrity: { type: string, description: 'sha512 of the tarball, as an SRI string (`sha512-{base64}`)' }
             tarball: { type: string, format: uri }
+            signatures:
+              type: array
+              description: |
+                The registry's signatures of `{id}@{version}:{integrity}`, by the keys at
+                `/-/npm/v1/keys`. Absent when the registry doesn't sign.
+              items:
+                type: object
+                required: [keyid, sig]
+                properties:
+                  keyid: { type: string }
+                  sig: { type: string, description: 'base64 DER ECDSA signature' }
+            fhir-signature:
+              type: object
+              description: |
+                The publisher's signature of this version, as this registry checked it, when
+                there is one. Absent when the package isn't signed, or its feed lists no keys.
+              required: [url, status]
+              properties:
+                url: { type: string, format: uri, description: 'The signature: `/-/fhir/v1/signatures/{name}@{version}`' }
+                status: { type: string, enum: [confirmed, rejected] }
+                keyid: { type: string, description: The key that signed it (when confirmed) }
+
+    SigningKeys:
+      type: object
+      required: [keys]
+      properties:
+        keys:
+          type: array
+          items:
+            type: object
+            required: [keyid, keytype, scheme, key]
+            properties:
+              keyid: { type: string, description: '`SHA256:` and the base64 sha256 of the key' }
+              keytype: { type: string, const: ecdsa-sha2-nistp256 }
+              scheme: { type: string, const: ecdsa-sha2-nistp256 }
+              key: { type: string, description: 'The public key: base64 DER SubjectPublicKeyInfo' }
+              expires: { type: [string, 'null'], format: date-time, description: 'null: no expiry' }
 
     BrokenDependencies:
       type: object