Feat: Ability to assign security schemas (#110)

* Additional types of SecuritySchemeObject.

* Adjusting the scopes in SecuritySchemeObject and OAuthFlowObject.

* Ref: moving to a separate file.

* Distributing by types.

* Distributing OAuthFlowsObject.

* Add security schemas to the operations with references.

* Server level security and changes to config.

* Fix: not applying security to emission.

* Ref: globalSecurity, testing.

* Ref: simpler, simple config has only global security.

* Ref: consistency: config sets defaults, NS is always complete.

* Readme: feature, Changelog: 1.2.0.

* Removing logging in test.

* 1.2.0-beta1

CHANGELOG.md

@@ -2,6 +2,50 @@
 
 ## Version 1
 
+### v1.2.0
+
+- Ability to describe security schemas on the server and namespace level:
+ - These security schemas go directly to the generated documentation.
+
+```ts
+// Single namespace
+import { createSimpleConfig } from "zod-sockets";
+
+const config = createSimpleConfig({
+ security: [
+ {
+ type: "httpApiKey",
+ description: "Server security schema",
+ in: "header",
+ name: "X-Api-Key",
+ },
+ ],
+});
+```
+
+```ts
+// Multiple namespaces
+import { Config } from "zod-sockets";
+
+const config = new Config({
+ security: [
+ {
+ type: "httpApiKey",
+ description: "Server security schema",
+ in: "header",
+ name: "X-Api-Key",
+ },
+ ],
+}).addNamespace({
+ security: [
+ {
+ type: "userPassword",
+ description: "Namespace security schema",
+ },
+ ],
+});
+```
+
 ### v1.1.0
 
 - Supporting Node 22.

README.md

@@ -613,3 +613,47 @@ const action = factory
  .example("input", ["example payload"])
  .example("output", ["example acknowledgement"]);
 ```
+
+### Adding security schemas to the documentation
+
+You can describe the security schemas for the generated documentation both on
+server and namespace levels.
+
+```ts
+// Single namespace
+import { createSimpleConfig } from "zod-sockets";
+
+const config = createSimpleConfig({
+ security: [
+ {
+ type: "httpApiKey",
+ description: "Server security schema",
+ in: "header",
+ name: "X-Api-Key",
+ },
+ ],
+});
+```
+
+```ts
+// Multiple namespaces
+import { Config } from "zod-sockets";
+
+const config = new Config({
+ security: [
+ {
+ type: "httpApiKey",
+ description: "Server security schema",
+ in: "header",
+ name: "X-Api-Key",
+ },
+ ],
+}).addNamespace({
+ security: [
+ {
+ type: "userPassword",
+ description: "Namespace security schema",
+ },
+ ],
+});
+```

example/example-documentation.yaml

@@ -1,7 +1,7 @@
 asyncapi: 3.0.0
 info:
  title: Example APP
- version: 1.1.0
+ version: 1.2.0-beta1
  contact:
  name: Anna Bocharova
  url: https://robintail.cz

package.json

@@ -1,6 +1,6 @@
 {
  "name": "zod-sockets",
- "version": "1.1.0",
+ "version": "1.2.0-beta1",
  "description": "Socket.IO solution with I/O validation and the ability to generate AsyncAPI specification and a contract for consumers",
  "type": "module",
  "main": "dist/index.cjs",

src/__snapshots__/documentation.spec.ts.snap

@@ -1979,3 +1979,88 @@ operations:
  - $ref: "#/channels/Root/messages/rootAckForIncomingTest"
 "
 `;
+
+exports[`Documentation > Security > should depict server and channel security 1`] = `
+"asyncapi: 3.0.0
+info:
+ title: Testing security
+ version: 3.4.5
+id: "urn:example:com:"
+defaultContentType: text/plain
+servers:
+ test:
+ host: example.com
+ pathname: /
+ protocol: https
+ security:
+ - $ref: "#/components/securitySchemes/serverSecurity0"
+channels:
+ Root:
+ address: /
+ title: Namespace /
+ bindings:
+ ws:
+ bindingVersion: 0.1.0
+ method: GET
+ headers:
+ type: object
+ properties:
+ connection:
+ type: string
+ const: Upgrade
+ upgrade:
+ type: string
+ const: websocket
+ query:
+ type: object
+ properties:
+ EIO:
+ type: string
+ const: "4"
+ description: The version of the protocol
+ transport:
+ type: string
+ enum:
+ - polling
+ - websocket
+ description: The name of the transport
+ sid:
+ type: string
+ description: The session identifier
+ required:
+ - EIO
+ - transport
+ externalDocs:
+ description: Engine.IO Protocol
+ url: https://socket.io/docs/v4/engine-io-protocol/
+ messages:
+ rootIncomingTest:
+ name: test
+ title: test
+ payload:
+ type: array
+ additionalItems: false
+components:
+ securitySchemes:
+ serverSecurity0:
+ type: httpApiKey
+ description: Sample security schema
+ in: header
+ name: X-Api-Key
+ rootSecurity0:
+ type: userPassword
+ description: Namespace level security sample
+operations:
+ RootRecvOperationTest:
+ action: receive
+ channel:
+ $ref: "#/channels/Root"
+ messages:
+ - $ref: "#/channels/Root/messages/rootIncomingTest"
+ title: test
+ summary: Incoming event test
+ description: The message consumed by the application within the / namespace
+ security:
+ - $ref: "#/components/securitySchemes/rootSecurity0"
+"
+`;

src/async-api/builder.ts

@@ -5,6 +5,7 @@ import {
  ServerObject,
 } from "./model";
 import yaml from "yaml";
+import { SecuritySchemeObject } from "./security";
 
 export class AsyncApiBuilder {
  protected readonly document: AsyncApiObject;
@@ -39,6 +40,17 @@ export class AsyncApiBuilder {
  return this;
  }
 
+ public addSecurityScheme(name: string, scheme: SecuritySchemeObject): this {
+ this.document.components = {
+ ...this.document.components,
+ securitySchemes: {
+ ...this.document.components?.securitySchemes,
+ [name]: scheme,
+ },
+ };
+ return this;
+ }
+
  getSpec(): AsyncApiObject {
  return this.document;
  }

src/async-api/model.ts

@@ -1,3 +1,4 @@
+import { SecuritySchemeObject } from "./security";
 import { WS } from "./websockets";
 
 /**
@@ -18,7 +19,7 @@ export interface ServerObject {
  title?: string;
  description?: string;
  variables?: Record<string, ServerVariableObject>;
- security?: SecuritySchemeObject[];
+ security?: Array<SecuritySchemeObject | ReferenceObject>;
  tags?: TagObject[];
  externalDocs?: ExternalDocumentationObject;
  bindings?: Bindings<WS.Server>;
@@ -264,7 +265,7 @@ export interface OperationTraitObject {
  title?: string;
  summary?: string;
  description?: string;
- security?: SecuritySchemeObject[];
+ security?: Array<SecuritySchemeObject | ReferenceObject>;
  tags?: TagObject[];
  externalDocs?: ExternalDocumentationObject;
  bindings?: Bindings<WS.Operation>;
@@ -324,48 +325,6 @@ export interface TagObject {
  externalDocs?: ExternalDocumentationObject;
 }
 
-export interface SecuritySchemeObject {
- type:
- | "userPassword"
- | "apiKey"
- | "X509"
- | "symmetricEncryption"
- | "asymmetricEncryption"
- | "http"
- | "oauth2"
- | "openIdConnect";
- description?: string;
- /** @desc for httpApiKey */
- name?: string;
- /** @desc Valid values are "user" and "password" for apiKey and "query", "header" or "cookie" for httpApiKey. */
- in?: "user" | "password" | "query" | "header" | "cookie";
- /** @desc for http */
- scheme?: string;
- /** @desc for http */
- bearerFormat?: string;
- /** @desc for oauth2 */
- flows?: OAuthFlowsObject;
- /** @desc for openIdConnect */
- openIdConnectUrl?: string;
-}
-
-export interface OAuthFlowsObject {
- implicit?: OAuthFlowObject;
- password?: OAuthFlowObject;
- clientCredentials?: OAuthFlowObject;
- authorizationCode?: OAuthFlowObject;
-}
-
-export interface OAuthFlowObject {
- /** @desc for implicit and authorizationCode */
- authorizationUrl?: string;
- /** @desc for password, clientCredentials and authorizationCode */
- tokenUrl?: string;
- refreshUrl?: string;
- /** @desc A map between the scope name and a short description for it. */
- scopes: Record<string, string>;
-}
-
 /** @since 3.0.0 partially extends SchemaObject; schema prop removed */
 export interface ParameterObject
  extends Pick<SchemaObject, "enum" | "default" | "description" | "examples"> {

src/async-api/security.ts

@@ -0,0 +1,82 @@
+interface FlowCommons {
+ /** @desc The URL to be used for obtaining refresh tokens. */
+ refreshUrl?: string;
+ /** @desc A map between the scope name and a short description for it. */
+ availableScopes: Record<string, string>;
+}
+
+interface AuthHavingFlow {
+ /** @desc The authorization URL to be used for this flow. */
+ authorizationUrl: string;
+}
+
+interface TokenHavingFlow {
+ /** @desc The token URL to be used for this flow. */
+ tokenUrl: string;
+}
+
+export interface OAuthFlowsObject {
+ implicit?: FlowCommons & AuthHavingFlow;
+ password?: FlowCommons & TokenHavingFlow;
+ clientCredentials?: FlowCommons & TokenHavingFlow;
+ authorizationCode?: FlowCommons & AuthHavingFlow & TokenHavingFlow;
+}
+
+interface HttpApiKeySecurity {
+ type: "httpApiKey";
+ /** @desc The name of the header, query or cookie parameter to be used. */
+ name: string;
+ in: "query" | "header" | "cookie";
+}
+
+interface ApiKeySecurity {
+ type: "apiKey";
+ in: "user" | "password";
+}
+
+interface HttpSecurity {
+ type: "http";
+ /** @link https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml */
+ scheme?: string;
+ /** @example "Bearer" */
+ bearerFormat?: string;
+}
+
+interface ScopesHavingSecurity {
+ /** @desc List of the needed scope names. An empty array means no scopes are needed. */
+ scopes?: string[];
+}
+
+interface OAuth2Security extends ScopesHavingSecurity {
+ type: "oauth2";
+ flows: OAuthFlowsObject;
+}
+
+interface OpenIdConnectSecurity extends ScopesHavingSecurity {
+ type: "openIdConnect";
+ /** @desc OpenId Connect URL to discover OAuth2 configuration values */
+ openIdConnectUrl: string;
+}
+
+interface OtherSecurity {
+ type:
+ | "userPassword"
+ | "X509"
+ | "symmetricEncryption"
+ | "asymmetricEncryption"
+ | "plain"
+ | "scramSha256"
+ | "scramSha512"
+ | "gssapi";
+}
+
+export type SecuritySchemeObject = {
+ description?: string;
+} & (
+ | HttpApiKeySecurity
+ | ApiKeySecurity
+ | HttpSecurity
+ | OAuth2Security
+ | OpenIdConnectSecurity
+ | OtherSecurity
+);