@andrewheberle/serverless-ssh-ca 0.22.0 → 0.23.0

package/README.md

@@ -239,12 +239,66 @@ sequenceDiagram
     deactivate Client
 ```
 
+## API
+
+The CA serves two versions of its API, which are documented in OpenAPI
+format at `/docs` and in [openapi.json](openapi.json):
+
+| Action                   | v3                              | v4                                              |
+|--------------------------|---------------------------------|-------------------------------------------------|
+| Get the CA public key    | `GET /api/v3/ca`                | `GET /api/v4/ca`                                |
+| Request user certificate | `POST /api/v3/user/certificate` | `POST /api/v4/user/certificates`                |
+| Revoke user certificate  | `POST /api/v3/user/revoke`      | `DELETE /api/v4/user/certificates/{serial}`     |
+| Get user KRL             | `GET /api/v3/user/krl`          | `GET /api/v4/user/krl`                          |
+| Request host certificate | `POST /api/v3/host/certificate` | `POST /api/v4/host/certificates`                |
+| Renew host certificate   | `POST /api/v3/host/renew`       | `POST /api/v4/host/certificates/{serial}/renew` |
+| Revoke host certificate  | `POST /api/v3/host/revoke`      | `DELETE /api/v4/host/certificates/{serial}`     |
+| Get host KRL             | `GET /api/v3/host/krl`          | `GET /api/v4/host/krl`                          |
+
+### Proof of Possession
+
+Requests that use an SSH key prove possession of its private key by including
+a proof of the form `${timestamp}.${fingerprint}.${signature}`, where
+`timestamp` is the time in milliseconds since the Unix epoch, `fingerprint` is
+the SHA256 fingerprint of the public key (for example
+`SHA256:79mq0wtpQMTvS4+Of8VzLN0qmYWNUyTXYmqKwhEgSLs`) and `signature` is the
+BASE64 encoded armored SSHSIG signature (as produced by `ssh-keygen -Y sign`)
+of the signed data. The proof is rejected if the timestamp is outside of
+`CERTIFICATE_REQUEST_TIME_SKEW_MAX` of the time on the CA.
+
+In v3 the proof is sent as the `proof` property of the request body and the
+signed data is `${timestamp}.${fingerprint}` using the
+`proof-of-possession@com.github.serverless-ssh-ca.andrewheberle` namespace.
+As this does not say which request the proof is for, a proof captured from one
+request may be replayed against another endpoint while it is valid.
+
+In v4 the proof is sent in the `Proof-Of-Possession` header and is bound to
+the request it is made for. The signed data is
+`${timestamp}.${fingerprint}.${METHOD} ${path}` using the
+`request-proof-of-possession@com.github.serverless-ssh-ca.andrewheberle`
+namespace, where `${METHOD} ${path}` is the request as documented in the
+OpenAPI schema with any parameters filled in, for example:
+
+```
+1765696780805.SHA256:79mq0wtpQMTvS4+Of8VzLN0qmYWNUyTXYmqKwhEgSLs.DELETE /api/v4/user/certificates/12345678901234567890
+```
+
+Only `${timestamp}.${fingerprint}.${signature}` is sent, as the CA rebuilds
+the request part from the request it receives. The path does not change if
+the CA is served behind a proxy under another path, and serials in the path
+are written in decimal without leading zeros.
+
+In v4 the public key for a revocation or renewal is taken from the proof and
+the certificate respectively, so it is not sent separately.
+
 ## Configuration
 
 ### CA Private Key
 
 The CA private key is read from the `PRIVATE_KEY` Secrets Store binding and
-must be an Ed25519 or ECDSA (`nistp256`, `nistp384` or `nistp521`) key:
+must be an unencrypted Ed25519 or ECDSA (`nistp256`, `nistp384` or
+`nistp521`) key in OpenSSH format, which is what `ssh-keygen` creates by
+default:
 
 ```sh
 ssh-keygen -t ed25519 -N "" -C "" -f ssh-ca

package/dist/api/operations.d.ts

@@ -0,0 +1,49 @@
+import { Logger } from "@andrewheberle/ts-slog";
+import type { AppContext } from "../router.js";
+import type { SshCertificate } from "../ssh/certificate.js";
+import { type PublicKey } from "../ssh/keys.js";
+import { CertificateType } from "../db/types.js";
+/**
+ * Returns the public key of the CA in OpenSSH format.
+ *
+ * @param c The request context
+ * @param l The logger for the request
+ * @returns The response containing the CA public key
+ */
+export declare const caPublicKey: (c: AppContext, l: Logger) => Promise<Response>;
+/**
+ * Returns the signed Key Revocation List for a type of certificate.
+ *
+ * @param c The request context
+ * @param l The logger for the request
+ * @param certificateType The type of certificate to return the KRL for
+ * @returns The response containing the KRL and its signature
+ */
+export declare const revocationList: (c: AppContext, l: Logger, certificateType: CertificateType) => Promise<Response>;
+/**
+ * Signs a certificate, records it so it can later be revoked and returns it
+ * as the response to a certificate request or renewal.
+ *
+ * These are the steps shared by every API version once a request has been
+ * validated and authorised.
+ *
+ * @param c The request context
+ * @param l The logger for the request
+ * @param sign Signs and returns the certificate
+ * @param certificateType The type of certificate being issued
+ * @returns The response containing the issued certificate
+ */
+export declare const issueCertificate: (c: AppContext, l: Logger, sign: () => Promise<SshCertificate>, certificateType: CertificateType) => Promise<Response>;
+/**
+ * Revokes a certificate once the requester has proven possession of the
+ * private key for the public key it was issued for.
+ *
+ * @param c The request context
+ * @param l The logger for the request
+ * @param serial The serial of the certificate to revoke
+ * @param publicKey The public key the requester has proven possession of
+ * @param certificateType The type of certificate being revoked
+ * @returns The response containing the time of revocation
+ */
+export declare const revoke: (c: AppContext, l: Logger, serial: bigint, publicKey: PublicKey, certificateType: CertificateType) => Promise<Response>;
+//# sourceMappingURL=operations.d.ts.map

package/dist/api/operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../src/api/operations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAQtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAG9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC3D,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE9D,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAgChD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,MAAa,UAAU,KAAK,MAAM,KAAG,OAAO,CAAC,QAAQ,CAQ5E,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,MAAa,UAAU,KAAK,MAAM,mBAAmB,eAAe,KAAG,OAAO,CAAC,QAAQ,CAkCjH,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,MAAa,UAAU,KAAK,MAAM,QAAQ,MAAM,OAAO,CAAC,cAAc,CAAC,mBAAmB,eAAe,KAAG,OAAO,CAAC,QAAQ,CAuCxJ,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,MAAM,MAAa,UAAU,KAAK,MAAM,UAAU,MAAM,aAAa,SAAS,mBAAmB,eAAe,KAAG,OAAO,CAAC,QAAQ,CAsC/I,CAAA"}

package/dist/api/operations.js

@@ -0,0 +1,175 @@
+import { group } from "@andrewheberle/ts-slog";
+import { ApiException, ConflictException, InternalServerErrorException, NotFoundException, UnprocessableEntityException, } from "chanfana";
+import { BadIssuerError } from "../certificate.js";
+import { KeyParseError } from "../ssh/keys.js";
+import { getPrivateKey, getPublic, UnsupportedKeyError } from "../utils.js";
+import { KRLBuilder } from "../krl.js";
+import { getKrlVersion, getRevocationList, recordCertificate, RevocationStatus, revocationStatus, revokeCertificate, } from "../db/index.js";
+/**
+ * Maps an error from an operation that uses the CA key to an API error.
+ */
+const caKeyError = (l, err) => {
+    switch (true) {
+        case (err instanceof UnsupportedKeyError):
+            l.error(err.message);
+            return new InternalServerErrorException(err.message);
+        case (err instanceof KeyParseError):
+            l.error("error parsing private key");
+            return new InternalServerErrorException("error parsing private key");
+        case (err instanceof ApiException):
+            // re-throw any exisiting chanfana error
+            return err;
+        default:
+            // otherwise throw as InternalServerErrorException
+            l.error("unhandled error", "error", err);
+            return new InternalServerErrorException("internal server error");
+    }
+};
+/**
+ * Returns the public key of the CA in OpenSSH format.
+ *
+ * @param c The request context
+ * @param l The logger for the request
+ * @returns The response containing the CA public key
+ */
+export const caPublicKey = async (c, l) => {
+    try {
+        const pub = await getPublic(c.env);
+        return c.text(`${pub.toString()}\n`);
+    }
+    catch (err) {
+        throw caKeyError(l, err);
+    }
+};
+/**
+ * Returns the signed Key Revocation List for a type of certificate.
+ *
+ * @param c The request context
+ * @param l The logger for the request
+ * @param certificateType The type of certificate to return the KRL for
+ * @returns The response containing the KRL and its signature
+ */
+export const revocationList = async (c, l, certificateType) => {
+    try {
+        // get revoked serials
+        const serials = (await getRevocationList(c.env, certificateType)).map(v => BigInt(v));
+        // grab private key from secret store
+        const key = await getPrivateKey(c.env);
+        // generate KRL
+        const krl = new KRLBuilder(key)
+            .addSerials(serials);
+        // the version only changes when the content of the KRL does
+        const version = await getKrlVersion(c.env, certificateType, await krl.digest());
+        const krlBytes = krl.generate(version);
+        // convert to base64
+        const bytes = new Uint8Array(krlBytes);
+        let binary = "";
+        for (const byte of bytes) {
+            binary += String.fromCharCode(byte);
+        }
+        const base64Krl = btoa(binary);
+        const signature = await krl.signature();
+        return c.json({
+            krl: base64Krl,
+            signature: signature,
+        });
+    }
+    catch (err) {
+        throw caKeyError(l, err);
+    }
+};
+/**
+ * Signs a certificate, records it so it can later be revoked and returns it
+ * as the response to a certificate request or renewal.
+ *
+ * These are the steps shared by every API version once a request has been
+ * validated and authorised.
+ *
+ * @param c The request context
+ * @param l The logger for the request
+ * @param sign Signs and returns the certificate
+ * @param certificateType The type of certificate being issued
+ * @returns The response containing the issued certificate
+ */
+export const issueCertificate = async (c, l, sign, certificateType) => {
+    try {
+        const certificate = await sign();
+        const response = {
+            certificate: btoa(certificate.toString())
+        };
+        try {
+            await recordCertificate(c.env, certificate, certificate.keyId, certificateType);
+        }
+        catch (err) {
+            // a certificate that is not recorded cannot be revoked, so do not issue it
+            l.error("there was a problem adding issued certificate to database", "error", err);
+            throw new InternalServerErrorException("there was a problem recording the issued certificate");
+        }
+        l.info("completed issuing certificate", ...group("certificate", "principals", certificate.principals.join(","), "serial", certificate.serial));
+        return c.json(response);
+    }
+    catch (err) {
+        switch (true) {
+            case (err instanceof UnsupportedKeyError):
+                l.error(err.message);
+                throw new InternalServerErrorException(err.message);
+            case (err instanceof ApiException):
+                // re-throw any exisiting chanfana error
+                throw err;
+            case (err instanceof BadIssuerError):
+                throw new UnprocessableEntityException(err.message);
+            default:
+                // otherwise throw as InternalServerErrorException
+                l.error("unhandled error", "error", err);
+                throw new InternalServerErrorException("internal server error");
+        }
+    }
+};
+/**
+ * Revokes a certificate once the requester has proven possession of the
+ * private key for the public key it was issued for.
+ *
+ * @param c The request context
+ * @param l The logger for the request
+ * @param serial The serial of the certificate to revoke
+ * @param publicKey The public key the requester has proven possession of
+ * @param certificateType The type of certificate being revoked
+ * @returns The response containing the time of revocation
+ */
+export const revoke = async (c, l, serial, publicKey, certificateType) => {
+    // ensure certificate can be revoked
+    const status = await revocationStatus(c.env, serial, publicKey, certificateType);
+    switch (status) {
+        case RevocationStatus.Revoked:
+            l.warn("certificate is already revoked");
+            throw new ConflictException("certificate is already revoked");
+        case RevocationStatus.NotFound:
+            l.warn("certificate not found");
+            throw new NotFoundException("certificate not found");
+    }
+    try {
+        const res = await revokeCertificate(c.env, serial);
+        if (res.length === 0) {
+            throw new InternalServerErrorException("no results were returned for revocation");
+        }
+        if (res.length > 1) {
+            l.warn("more than one revocation result was returned", "count", res.length);
+        }
+        l.info("completed revocation");
+        return c.json({
+            revoked_at: res[0].revoked_at
+        });
+    }
+    catch (err) {
+        switch (true) {
+            case (err instanceof ApiException):
+                // re-throw any exisiting chanfana error
+                throw err;
+            default:
+                // otherwise throw as InternalServerErrorException
+                l.error("unhandled error", "error", err);
+                throw new InternalServerErrorException("internal server error");
+        }
+    }
+};
+//# sourceMappingURL=operations.js.map

package/dist/api/operations.js.map

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

package/dist/api/schema.d.ts

@@ -0,0 +1,71 @@
+import z from "zod";
+import type { SshCaBindings } from "../types.js";
+import { CertificateType } from "../db/types.js";
+/**
+ * Returns the name of a {@link CertificateType} as used in API paths and logs
+ * @param certificateType The type of certificate
+ * @returns "user" or "host"
+ */
+export declare const certificateTypeName: (certificateType: CertificateType) => "user" | "host";
+/**
+ * Returns the OpenAPI tag that groups the endpoints for a {@link CertificateType}
+ * @param certificateType The type of certificate
+ * @returns "User" or "Host"
+ */
+export declare const certificateTypeTag: (certificateType: CertificateType) => "User" | "Host";
+export declare const openapiStringByte: z.ZodPipe<z.ZodBase64, z.ZodTransform<Buffer<ArrayBuffer>, string>>;
+export declare const proofOfPossession: z.ZodString;
+export declare const publicKey: z.ZodPipe<z.ZodPipe<z.ZodBase64, z.ZodTransform<Buffer<ArrayBuffer>, string>>, z.ZodTransform<import("../ssh/keys.js").PublicKey, Buffer<ArrayBuffer>>>;
+export declare const createIdentityTokenSchema: (env: SshCaBindings) => z.ZodPipe<z.ZodString, z.ZodTransform<{
+    sub: string;
+    principals: string[];
+}, string>>;
+export declare const createAccessTokenSchema: (env: SshCaBindings) => z.ZodPipe<z.ZodString, z.ZodTransform<{
+    email: string;
+    sub: string;
+}, string>>;
+export declare const krl: z.ZodPipe<z.ZodBase64, z.ZodTransform<Buffer<ArrayBuffer>, string>>;
+export declare const createHeaderSchema: (env: SshCaBindings) => z.ZodObject<{
+    Authorization: z.ZodPipe<z.ZodString, z.ZodTransform<{
+        email: string;
+        sub: string;
+    }, string>>;
+}, z.core.$strip>;
+export declare const certificate: z.ZodPipe<z.ZodBase64, z.ZodTransform<Buffer<ArrayBuffer>, string>>;
+export declare const CaPublicKeyEndpointSchema: {
+    tags: string[];
+    summary: string;
+    description: string;
+    responses: {
+        "200": {
+            content: {
+                "text/plain": {
+                    schema: z.ZodString;
+                };
+            };
+            description: string;
+        };
+    };
+};
+export declare const createRevocationListEndpointSchema: (certificateType: CertificateType) => {
+    tags: ("Host" | "User")[];
+    summary: string;
+    description: string;
+    responses: {
+        "200": {
+            content: {
+                "application/json": {
+                    schema: z.ZodType<{
+                        krl: Buffer<ArrayBuffer>;
+                        signature: string;
+                    }, unknown, z.core.$ZodTypeInternals<{
+                        krl: Buffer<ArrayBuffer>;
+                        signature: string;
+                    }, unknown>>;
+                };
+            };
+            description: string;
+        };
+    };
+};
+//# sourceMappingURL=schema.d.ts.map

package/dist/api/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/api/schema.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,KAAK,CAAA;AACnB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAUhD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAEhD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,oBAAqB,eAAe,KAAG,MAAM,GAAG,MAW/E,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,oBAAqB,eAAe,KAAG,MAAM,GAAG,MAW9E,CAAA;AAED,eAAO,MAAM,iBAAiB,qEASD,CAAA;AAE7B,eAAO,MAAM,iBAAiB,aAI3B,CAAA;AAEH,eAAO,MAAM,SAAS,yJAKnB,CAAA;AAEH,eAAO,MAAM,yBAAyB,QAAS,aAAa;;;WAO3D,CAAA;AAED,eAAO,MAAM,uBAAuB,QAAS,aAAa;;;WAOzD,CAAA;AAED,eAAO,MAAM,GAAG,qEAC8B,CAAA;AAE9C,eAAO,MAAM,kBAAkB,QAAS,aAAa;;;;;iBAIpD,CAAA;AAED,eAAO,MAAM,WAAW,qEACqB,CAAA;AAE7C,eAAO,MAAM,yBAAyB;;;;;;YAMnC,OAAO;gBACN,YAAY;oBACX,MAAM;;;YAGR,WAAW;;;CAIb,CAAA;AAED,eAAO,MAAM,kCAAkC,oBAAqB,eAAe;;;;;;;;;;;;;;;;;;;;CAgBjF,CAAA"}

package/dist/api/schema.js

@@ -0,0 +1,107 @@
+import z from "zod";
+import { transformAuthorizationHeader, transformPublicKey, transformIdentityToken, } from "../utils.js";
+import { contentJson, InternalServerErrorException, } from "chanfana";
+import { CertificateType } from "../db/types.js";
+/**
+ * Returns the name of a {@link CertificateType} as used in API paths and logs
+ * @param certificateType The type of certificate
+ * @returns "user" or "host"
+ */
+export const certificateTypeName = (certificateType) => {
+    switch (certificateType) {
+        case CertificateType.User:
+            return "user";
+        case CertificateType.Host:
+            return "host";
+        default: {
+            const unknownType = certificateType;
+            throw new Error(`unknown certificate type: ${String(unknownType)}`);
+        }
+    }
+};
+/**
+ * Returns the OpenAPI tag that groups the endpoints for a {@link CertificateType}
+ * @param certificateType The type of certificate
+ * @returns "User" or "Host"
+ */
+export const certificateTypeTag = (certificateType) => {
+    switch (certificateType) {
+        case CertificateType.User:
+            return "User";
+        case CertificateType.Host:
+            return "Host";
+        default: {
+            const unknownType = certificateType;
+            throw new Error(`unknown certificate type: ${String(unknownType)}`);
+        }
+    }
+};
+export const openapiStringByte = z.base64()
+    .transform((v) => {
+    const a = z.util.base64ToUint8Array(v);
+    return Buffer.from(a.buffer, a.byteOffset, a.length);
+})
+    .openapi({ format: "byte" });
+export const proofOfPossession = z.string()
+    .meta({
+    description: "Proof of possession comprising of ${timestamp}.${fingerprint}.${signature}",
+    example: "1765696780805.SHA256:79mq0wtpQMTvS4+Of8VzLN0qmYWNUyTXYmqKwhEgSLs.LS0tLS1CRUdJTiBTU0ggU0lHTkFUVVJFLS0tLS0KVTFOSVUwbEhBQUFBQVFBQUFHZ0FBQUFUWldOa2MyRXRjMmhoTWkxdWFYTjBjREkxTmdBQUFBaHVhWE4wY0RJMQpOZ0FBQUVFRUR6Ymk4OE10alBYSDFCb1JURU9HaS96aEc4QnhQNVZUUW5OQkFNMGZtMExtekErUUZkUlNVYVRFCkdNN2l0QjhINmZNZFAydlAxcElQcGUyOWVLQkJZd0FBQUFSbWFXeGxBQUFBQUFBQUFBWnphR0UxTVRJQUFBQmsKQUFBQUUyVmpaSE5oTFhOb1lUSXRibWx6ZEhBeU5UWUFBQUJKQUFBQUlHdmZVZGNDQkRXa3ZwL0ZHS3NkakgrRQpKZzZXN0EvWUJVZng2Z0srQ01raEFBQUFJUUQxOFd5cDNZejZ0eXNvdllXbEJHTXprRnlYbFRrSHM5blVVRXJqCkczNWVPQT09Ci0tLS0tRU5EIFNTSCBTSUdOQVRVUkUtLS0tLQo="
+});
+export const publicKey = openapiStringByte
+    .transform(transformPublicKey)
+    .meta({
+    description: "SSH public key to sign",
+    example: "ZWNkc2Etc2hhMi1uaXN0cDI1NiBBQUFBRTJWalpITmhMWE5vWVRJdGJtbHpkSEF5TlRZQUFBQUlibWx6ZEhBeU5UWUFBQUJCQkdNcFNKdHRmMEl0dE5DVmMyOFR6WEZSMUQweHZPM25wNjdWemVBUXNiZFpza3JEY1lqU2x3SjZIUERtVHBYYVUwbEVhWDlMNFloYy9jQ2YxTWU5RlRrPQo="
+});
+export const createIdentityTokenSchema = (env) => (z.string()
+    .meta({
+    description: "Identity Token JWT from OIDC IdP",
+    example: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiZW1haWwiOiJ1c2VyQGV4YW1wbGUuY29tIiwiaWF0IjoxNzc1NzAzMDk1fQ.ri_neAWnhMNK3LzlsrBcQYymSM4yRjmNSZZSeZiXhrEqtEz6c3cXk0Esq765umGjpUsWcosL-OFrDJlyAjTDnhrd9oV08uc_CW0rQRsJIGEuRo3ryxkLdVu9mGoZWEUb9KwjGJrwxvr-0cPWx5jaDyKwJcqMvtV_bEITUD51sDB1Vm89QfYRO_pGJo2vrRzSvMjpUenRpwPay4lYIBxl41_4YpR9Rc6VrIZuYsjV2iqEZ4eBrygMA7zPR_hN7l7s95FddLOzj5NsK57VT4uLHwYohx2oqMzw3M-B9HsZIQin_9q61pZFQXepzJth0woXiZheU27llnfHX967PhNQyg"
+})
+    .transform((val, ctx) => transformIdentityToken(env, val, ctx)));
+export const createAccessTokenSchema = (env) => (z.string()
+    .meta({
+    description: "Access Token JWT from OIDC IdP",
+    example: "Bearer eyJ..."
+})
+    .transform((val, ctx) => transformAuthorizationHeader(env, val, ctx)));
+export const krl = openapiStringByte
+    .meta({ description: "Key Revocation List" });
+export const createHeaderSchema = (env) => (z.object({
+    "Authorization": createAccessTokenSchema(env)
+}));
+export const certificate = openapiStringByte
+    .meta({ description: "Issued Certificate" });
+export const CaPublicKeyEndpointSchema = {
+    tags: ["CA"],
+    summary: "Get the CA public key",
+    description: "Returns the public key of the SSH Certificate Authority in OpenSSH format, for use in `TrustedUserCAKeys` on SSH servers or `@cert-authority` entries in `known_hosts` on SSH clients.",
+    responses: {
+        "200": {
+            content: {
+                "text/plain": {
+                    schema: z.string()
+                }
+            },
+            description: "Returns SSH Certificate Authority Public Key",
+        },
+        ...InternalServerErrorException.schema(),
+    }
+};
+export const createRevocationListEndpointSchema = (certificateType) => ({
+    tags: [certificateTypeTag(certificateType)],
+    summary: `Get the Key Revocation List for ${certificateTypeName(certificateType)} certificates`,
+    description: `Returns the OpenSSH Key Revocation List (KRL) of revoked ${certificateTypeName(certificateType)} certificates issued by this CA, along with an SSHSIG signature made by the CA key so the KRL can be verified before use.`,
+    responses: {
+        "200": {
+            description: `Returns an Open SSH Key Revocation List of revoked ${certificateTypeName(certificateType)} certificates as BASE64 and an SSHSIG signature for verification`,
+            ...contentJson(z.object({
+                krl: krl,
+                signature: z.string()
+            })
+                .openapi("Key Revocation List Response"))
+        },
+        ...InternalServerErrorException.schema(),
+    }
+});
+//# sourceMappingURL=schema.js.map

package/dist/api/schema.js.map

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

package/dist/api/v3/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/v3/index.ts"],"names":[],"mappings":"AAkDA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAwXnD,eAAO,MAAM,SAAS,QAAS,aAAa,mHAa3C,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/v3/index.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AA0KnD,eAAO,MAAM,SAAS,QAAS,aAAa,mHAa3C,CAAA"}