Merge pull request #106 from polyphony-chat/typespec

TypeSpec

.gitattributes

@@ -1,3 +1,4 @@
 *.md linguist-detectable
 styles/* linguist-vendored
-styles/config linguist-detectable
+styles/config linguist-detectable
+*.tsp linguist-language=TypeSpec

.github/dependabot.yml

@@ -9,4 +9,10 @@ updates:
     directory: "/" # Location of package manifests
     schedule:
       interval: "weekly"
-
+  - package-ecosystem: "npm"
+    directories:
+      - "/api/core"
+      - "/api/auth"
+      - "/api/chat"
+    schedule:
+      interval: "weekly"

.github/workflows/deploy-openapi-spec.yml

@@ -0,0 +1,37 @@
+name: Build and Deploy OpenAPI configuration
+on:
+    push:
+      branches:
+        - main
+    workflow_dispatch: 
+permissions:
+  contents: write
+jobs:
+    build_and_deploy:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v4
+            with:
+              fetch-depth: 0
+          - name: Configure git Credentials
+            run: |
+                git config user.name github-actions[bot]
+                git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+          - uses: actions/setup-node@v4
+            with:
+              node-version: "lts/*"
+              cache: "npm"
+              cache-dependency-path: "./api/core/package-lock.json"
+          - name: Install TypeSpec and compile project
+            run: |
+              cd ./api/src/core/
+              npm install -g @typespec/compiler
+              npm install
+              tsp compile .
+          - name: Commit OpenAPI specification to repository
+            run: |
+              cd ../../
+              mv ./src/core/tsp-output/@typespec/openapi3/openapi.v1.0.yaml ./build/core-openapi3.yaml
+              git add ./build/*
+              git commit -m "[bot]update openapi3 schema"
+              git push

.gitignore

@@ -1,3 +1,11 @@
+# typespec
+
+# Default TypeSpec output
+dist/
+
+# Dependency directories
+node_modules/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -8,7 +16,6 @@ __pycache__/
 
 # Distribution / packaging
 .Python
-build/
 develop-eggs/
 dist/
 downloads/

.vscode/extensions.json

@@ -3,6 +3,7 @@
         "davidanson.vscode-markdownlint",
         "chrischinchilla.vale-vscode",
         "valentjn.vscode-ltex",
-        "gruntfuggly.todo-tree"
+        "gruntfuggly.todo-tree",
+        "typespec.typespec-vscode"
     ]
 }

.vscode/ltex.dictionary.en-US.txt

@@ -19,3 +19,6 @@ polyproto-auth
 CAs
 TTLs
 NLnet
+OpenAPI
+TypeSpec
+Protobuf

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 polyphony
+Copyright (c) 2023 The "polyphony-chat" GitHub Organization and all "docs" repository contributors.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -5,10 +5,15 @@ Built with mkdocs-material and python3.12
 
 ## File structure
 
-The `/docs` folder has the specification documents for the polyproto protocol. The `docs/APIs` folder houses the API documentation for the polyproto-core and polyphony-chat reference implementation.
+The `/docs` folder has the specification documents for the polyproto protocol.
 
 The `/snippets` folder has snippets of text used in many places in the documentation. This is to ensure consistency across the documentation. Error messages appearing in many places are also stored in the `/snippets/errors` folder.
 
+API documentation in form of [TypeSpec](https://typespec.io) files can be found in the `/api` directory.
+TypeSpec can compile to OpenAPI3, JSON Schema and Protobuf. Our TypeSpec project is targeting OpenAPI3
+output. Read the TypeSpec documentation for information on how to compile TypeSpec or use a pre-compiled
+version of the OpenAPI schema if you'd like.
+
 ## Contributing
 
 The best way to contribute is to open an issue if you find any problems with the documentation. Creating an issue is generally the best way to contribute to any open source project. Issues allow for an exchange between contributors and maintainers to discuss the viability of implementing an issue, usually minimizing frustration.

api/build/README.md

@@ -0,0 +1,3 @@
+# polyproto OpenAPI3 specification
+
+This folder contains pre-compiled OpenAPI3 specification documents for polyproto.

api/src/core/.gitignore

@@ -0,0 +1,9 @@
+# MacOS
+.DS_Store
+
+# Default TypeSpec output
+tsp-output/
+dist/
+
+# Dependency directories
+node_modules/

api/src/core/README.md

@@ -0,0 +1,5 @@
+# polyproto-core TypeSpec Project
+
+See [the TypeSpec documentation on installing TypeSpec and getting in running](https://typespec.io/docs/)
+first. Then, install dependencies using `tsp install` and generate OpenAPI specification output using
+`tsp compile .`.

api/src/core/main.tsp

@@ -0,0 +1,95 @@
+import "@typespec/http";
+import "@typespec/rest";
+import "@typespec/openapi3";
+import "./routes";
+
+using TypeSpec.Http;
+using Routes;
+
+namespace polyproto.core;
+
+namespace models {
+    model EncryptedPKM {
+        /**
+         * Custom variant of the X.509 `SubjectPublicKeyInfo`, where the `subject_public_key`
+         * field stores the encrypted private key, instead of a public key. Otherwise equal to
+         * `SubjectPublicKeyInfo`. Also referred to as `PrivateKeyInfo`.
+         */
+        key_data: string,
+        @doc("The serial number of the ID-Cert this key material is associated with.")
+        serial_number: uint64,
+        /**
+         * Information about the algorithms used to encrypt the data held by the `key_data` field.
+         * Order-sensitive; The encryption used for the first encryption operation must be the last
+         * item of this array and vice versa. Represents a list of OIDs.
+         */
+        @minItems(1)
+        encryption_algorithms: Array<Array<uint16>>
+    }
+
+    /**
+     * A resource representing information about a discoverable service for an actor. You can learn more about
+     * services and discoverability by reading [section #9](/Protocol Specifications/core#9-services) of
+     * the core protocol specification.
+     *
+     * This resource contains information about the name of the service that is being made discoverable,
+     * the URL of the service provider, and whether this service provider is the primary service provider
+     * for the actor.
+     */
+    model Service {
+        @minLength(2)
+        @maxLength(64)
+        @doc("The name of the service that is being made discoverable. Must be formatted according to [section #8.2: Namespaces](/Protocol Specifications/core#82-namespaces) in the core protocol specification")
+        service: string,
+        @doc("The base URL of the service provider, not including `/.p2/<service_name>`. Trailing slashes are allowed. If `(/).p2/<service_name>` is added to the URL specified here, a polyproto client should be able to access the HTTP API routes provided by the service.")
+        url: url,
+        @doc("Whether the service provider specified in the url field is the primary service provider for this service and actor.")
+        primary: boolean
+    }
+
+    /**
+     * A challenge string response, as received from a server when requesting a challenge string.
+     * 
+     * From the polyproto protocol definition: "verify an actor's private identity key possession,
+     * without revealing the private key itself. These strings, ranging from 32 to 256 characters,
+     * have a UNIX timestamp lifetime. If the current timestamp surpasses this lifetime, the
+     * challenge fails. The actor signs the string, sending the signature and their ID-Cert to the
+     * server, which then verifies the signature's authenticity."
+     */
+    model ChallengeStringResponse {
+        @minLength(32)
+        @maxLength(256)
+        @doc("The challenge string, which the client should sign with its private identity key.") 
+        challenge: string,
+        @doc("The UNIX timestamp after which the challenge expires.")
+        expires: uint64
+    }
+
+    /**
+     * A key trial as sent from the server to an actor.
+     */
+    model KeyTrial {
+        @minLength(32)
+        @maxLength(256)
+        @doc("The key trial, which the client should sign with all of their private identity keys.") 
+        trial: string;
+        @minLength(1)
+        @maxLength(256)
+        @doc("A unique identifying string to differentiate this specific key trial from other key trials that may be open at the same time.")
+        id: string,
+        @doc("The UNIX timestamp after which the key trial expires.")
+        expires: uint64;
+    }
+
+    /**
+     * A completed key trial, as an actor would send to the server.
+     */
+    model KeyTrialCompleted {
+        @doc("The signature produced by signing the key trial string using a private identity key.")
+        signature: string;
+        @doc("The unique identifying string, differentiating this specific key trial from other key trials that may be open at the same time.")
+        id: string,
+        @doc("The serial number of the ID-Cert corresponding to the private identity key used to sign the key trial string.")
+        serial_number: uint64;
+    }
+}