Skip to content
This repository was archived by the owner on Aug 15, 2025. It is now read-only.

Commit 2e5cc12

Browse files
bitfl0werbitfl0wer
committed
Split project into smaller files
1 parent 667a12e commit 2e5cc12

File tree

5 files changed

+606
-560
lines changed

5 files changed

+606
-560
lines changed

‎api/src/core/main.tsp‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@ import "./routes";
55

66
using TypeSpec.Http;
77
using Routes;
8+
using FederatedIdentity;
9+
using Services;
10+
using Migration;
811

912
namespace polyproto.core;
1013

‎api/src/core/routes/federated_identity.tsp‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
import "@typespec/http";
2+
import "@typespec/versioning";
3+
import "@typespec/openapi";
4+
import "@typespec/openapi3";
5+
import "../main.tsp";
6+
import "./main.tsp";
7+
8+
using TypeSpec.Http;
9+
using TypeSpec.Versioning;
10+
using TypeSpec.OpenAPI;
11+
using polyproto;
12+
using Routes;
13+
14+
namespace Routes;
15+
16+
namespace FederatedIdentity {
17+
@tag("Federated Identity - Registration required")
18+
@useAuth(BearerAuth)
19+
namespace Registered {
20+
@route("/session/idcert")
21+
@summary("Rotate session ID-Cert")
22+
@added(Version.`v1.0-alpha.1`)
23+
@post
24+
/**
25+
* Rotate your keys for a given session. The `session_id` in the supplied `csr` must correspond to the
26+
* session token used in the `authorization`-Header.
27+
* @param csr A new [certificate signing request (CSR)](/Protocol%20Specifications/core/#71-home-server-signed-certificates-for-public-client-identity-keys-id-cert) with the same session ID
28+
* @returns Contains your new ID-Cert, along with a new session token.
29+
*/
30+
op rotateIdCert(@body csr: string;): {
31+
@doc("Contains your new ID-Cert in PEM encoding, along with a new session token.")
32+
@statusCode statusCode: 201;
33+
@body newIdCert: {
34+
@doc("The generated [ID-Cert](/Protocol%20Specifications/core/#71-home-server-signed-certificates-for-public-client-identity-keys-id-cert) in PEM format.")
35+
@example("------BEGIN CERTIFICATE------...")
36+
id_cert: string,
37+
@doc("An authorization secret, called a \"token\", valid for this `id_cert`.")
38+
token: string
39+
}
40+
};
41+
42+
@route("/session/keymaterial")
43+
@summary("Upload encrypted private key material")
44+
@added(Version.`v1.0-alpha.1`)
45+
@post
46+
/**
47+
* Upload encrypted private key material to the server for later retrieval. The size of
48+
* the individual array elements must not exceed
49+
* the server's maximum upload size for this route. This is usually not more than 10kb and can be as
50+
* low as 800 bytes, depending on the server configuration.
51+
* @param pkm Array of encrypted private key material objects.
52+
*/
53+
op uploadEncryptedPKM(@body @minItems(1) pkm:
54+
polyproto.core.models.EncryptedPKM[]): {
55+
@statusCode statusCode: 201;
56+
} | {
57+
@doc("Used, if the `serial_number` does not match any known ID-Cert from this actor.")
58+
@statusCode statusCode: 404;
59+
} | {
60+
@doc("Status code for when the server already has key material for the given `serial_number`. The client would need to delete the existing key material before uploading new key material.")
61+
@statusCode statusCode: 409;
62+
} | {
63+
@doc("Uploaded key material exceeds the server's maximum upload size.")
64+
@statusCode statusCode: 413;
65+
};
66+
67+
@route("/session/keymaterial")
68+
@summary("Get encrypted private key material")
69+
@added(Version.`v1.0-alpha.1`)
70+
@get
71+
/**
72+
* Retrieve encrypted private key material from the server. The `serial_numbers`, if
73+
* provided, must match the serial numbers of ID-Certs that the client has uploaded key
74+
* material for. If no `serial_numbers` are provided, the server will return all key
75+
* material that the client has uploaded.
76+
*/
77+
op getEncryptedPKM(@query serials?: uint64[]): {
78+
@statusCode statusCode: 200;
79+
@body encryptedPKMs: polyproto.core.models.EncryptedPKM[];
80+
} | {
81+
@doc("Returned, if no `serial_numbers` are provided and the client has not uploaded any key material.")
82+
@statusCode statusCode: 204;
83+
} | {
84+
@doc("Returned, if none of the `serial_numbers` match any known ID-Certs from this actor.")
85+
@statusCode statusCode: 404;
86+
};
87+
88+
@route("/session/keymaterial")
89+
@tag("Sensitive Action")
90+
@summary("Delete encrypted private key material")
91+
@added(Version.`v1.0-alpha.1`)
92+
@delete
93+
/**
94+
* Delete encrypted private key material from the server. The `serial_number(s)`, must match
95+
* the serial numbers of ID-Certs that the client has uploaded key material for.
96+
*/
97+
op deleteEncryptedPKM(
98+
@doc("Sensitive actions require a [challenge string solution](/docs/Protocol%20Specifications/core.md) to be executed.")
99+
@header({name: "X-P2-CHALLENGE-STRING-SOLUTION"}) challengeStringSolution: string,
100+
@query serials: uint64[]): {
101+
@statusCode statusCode: 204;
102+
} | {
103+
@doc("Returned, if none of the `serial_numbers` match any known ID-Certs from this actor.")
104+
@statusCode statusCode: 404;
105+
};
106+
107+
@route("/session/keymaterial/size")
108+
@summary("Get encrypted private key material upload size limit")
109+
@added(Version.`v1.0-alpha.1`)
110+
@get
111+
@useAuth(NoAuth)
112+
/**
113+
* Retrieve the maximum upload size for encrypted private key material, in bytes.
114+
*
115+
* @returns The upload size limit, in bytes.
116+
*/
117+
op encryptedPKMsizeLimit(): {
118+
@header({name: "X-MAX-PAYLOAD-SIZE"}) size: uint32;
119+
@statusCode statusCode: 200;
120+
};
121+
}
122+
123+
@tag("Federated Identity - Registration not required")
124+
namespace Unregistered {
125+
@route("/challenge")
126+
@summary("Get challenge string")
127+
@useAuth(BearerAuth)
128+
@added(Version.`v1.0-alpha.1`)
129+
@get
130+
/**
131+
* Request a challenge string. See the corresponding
132+
* [protocol definition chapter](/docs/Protocol%20Specifications/core/#)
133+
* for more information.
134+
*/
135+
op challengeString(): {
136+
@statusCode statusCode: 200;
137+
@body challengeStringResponse: polyproto.core.models.ChallengeStringResponse
138+
};
139+
140+
@route("/key/server")
141+
@summary("Rotate Server Identity Key")
142+
@added(Version.`v1.0-alpha.1`)
143+
@post
144+
@useAuth(BearerAuth)
145+
@tag("Sensitive Action")
146+
/**
147+
* Rotate the server's identity key. Requires server administrator permissions.
148+
* @returns The servers' new ID-Cert, encoded as PEM
149+
*/
150+
op name(@header({name: "X-P2-CHALLENGE-STRING-SOLUTION"}) challengeStringSolution: string): string;
151+
152+
@route("/idcert/server")
153+
@get
154+
@added(Version.`v1.0-alpha.1`)
155+
@summary("Get Server ID-Cert")
156+
/**
157+
* Request the server's public identity certificate.
158+
* @returns The current ID-Cert of the server, or, if specified, the ID-Cert the server had
159+
* at the specified time.
160+
* @param timestamp An optional UNIX timestamp to retrieve the ID-Cert the server had at that
161+
* point in time, instead of the current one.
162+
*/
163+
op serverIdCert(@query timestamp?: uint64): string;
164+
165+
@route("/key/server")
166+
@get
167+
@added(Version.`v1.0-alpha.1`)
168+
@summary("Get Server Public Key")
169+
/**
170+
* Request the server's public key.
171+
* @returns The current public key of the server, or, if specified, the public key the server had
172+
* at the specified time. The public key is being returned as a PEM encoded X.509
173+
* `SubjectPublicKeyInfo`.
174+
* @param timestamp An optional UNIX timestamp to retrieve the public key the server had at that
175+
* point in time, instead of the current one.
176+
*/
177+
op serverKey(@query timestamp?: {
178+
timestamp: uint64
179+
}): string;
180+
181+
@route("/idcert/actor")
182+
@get
183+
@added(Version.`v1.0-alpha.1`)
184+
@summary("Get Actor ID-Cert(s)")
185+
/**
186+
* Request the ID-Certs of a specific actor. The specified actor must be registered on this server.
187+
* @param fid The ID of the actor whose ID-Cert(s) should be returned.
188+
* @param timestamp An optional UNIX timestamp to retrieve the ID-Cert the actor had at that
189+
* point in time, instead of the current one.
190+
* @param session_id Optionally, return only the ID-Certs matching a specific `session_id`.
191+
* @param body timestamp: UNIX-Timestamp. If specified, the server will return the ID-Cert(s) which the actor had at the specified time. session_id: Request the ID-Cert for a specific session ID.
192+
* @returns JSON-Array of Object(s), each object containing "id_cert" (PEM encoded ID-Cert) and "invalidated" (boolean). An ID-Cert is considered invalidated, if the server or actor choose to revoke the validity of the ID-Cert before the lifetime of the certificate was scheduled to end.
193+
*/
194+
op actorCerts(@path fid: string, @query timestamp?: uint64, @query session_id?: string): {
195+
@statusCode statusCode: 200;
196+
@body response: {
197+
@doc("PEM encoded ID-Cert")
198+
@example("------BEGIN CERTIFICATE------...")
199+
id_cert: string,
200+
@example(false)
201+
@doc("Whether this specific id_cert has been marked as invalidated by the server. An ID-Cert is considered invalidated, if the server or actor choose to revoke the validity of the ID-Cert before the lifetime of the certificate was scheduled to end.")
202+
invalidated: boolean
203+
}[]
204+
};
205+
206+
@route("/session/idcert/extern")
207+
@put
208+
@added(Version.`v1.0-alpha.1`)
209+
@useAuth(BearerAuth)
210+
@summary("Update session ID-Cert")
211+
/**
212+
* Lets a foreign server know that the ID-Cert of this session has changed.
213+
*/
214+
op updateSessionCert(@body id_cert: string): {
215+
@statusCode statusCode: 201;
216+
};
217+
218+
@route("/session")
219+
@delete
220+
@added(Version.`v1.0-alpha.1`)
221+
@summary("Delete/Revoke Session")
222+
@useAuth(BearerAuth)
223+
/**
224+
* Invalidate a session token by naming the session ID associated with it.
225+
*/
226+
op deleteSession(@query session_id: string): {
227+
@statusCode statusCode: 204;
228+
@header({name: "Content-Length"}) contentLength: 0;
229+
} | {
230+
@statusCode statusCode: 404;
231+
};
232+
}
233+
}

0 commit comments

Comments
 (0)