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

Commit 8761989

Browse files
bitfl0werbitfl0wer
committed
reformat file, remove challenge string route
1 parent 14b32e3 commit 8761989

File tree

1 file changed

+138
-102
lines changed

1 file changed

+138
-102
lines changed

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

Lines changed: 138 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -17,206 +17,242 @@ namespace FederatedIdentity {
1717
@tag("Federated Identity - Registration required")
1818
@useAuth(BearerAuth)
1919
namespace Registered {
20-
20+
/**
21+
* Request a new ID-Cert, usually done when wanting to authenticate a new session, or after
22+
* an ID-Cert has been revoked, to re-authenticate a session.
23+
*/
2124
@route("/idcert")
2225
@summary("Get a new ID-Cert")
2326
@added(Version.`v1.0-alpha.1`)
2427
@post
2528
@tag("Sensitive Actions")
26-
/**
27-
* Request a new ID-Cert, usually done when wanting to authenticate a new session, or after
28-
* an ID-Cert has been revoked, to re-authenticate a session.
29-
*/
3029
op newIdCert(
3130
@doc("Sensitive actions require a second factor of authentication to be executed. Read [section 4.1.2 of the protocol definition](https://docs.polyphony.chat/Protocol%20Specifications/core/#412-sensitive-actions) for more information.")
32-
@header({name: "X-P2-Sensitive-Solution"}) sensitiveSolution: string,
33-
@body csr: string;
34-
): {
35-
@doc("Contains your new ID-Cert in PEM encoding, along with a new session token.")
36-
@statusCode statusCode: 201;
37-
@body newIdCert: {
38-
@doc("The generated [ID-Cert](/Protocol%20Specifications/core/#71-home-server-signed-certificates-for-public-client-identity-keys-id-cert) in PEM format.")
39-
@example("------BEGIN CERTIFICATE------...")
40-
id_cert: string,
41-
@doc("An authorization secret, called a \"session token\", valid for this `id_cert`/session.")
42-
token: string
43-
}
31+
@header({
32+
name: "X-P2-Sensitive-Solution",
33+
})
34+
sensitiveSolution: string,
35+
36+
@body csr: string,
37+
): {
38+
@doc("Contains your new ID-Cert in PEM encoding, along with a new session token.")
39+
@statusCode
40+
statusCode: 201;
41+
42+
@body newIdCert: {
43+
@doc("The generated [ID-Cert](/Protocol%20Specifications/core/#71-home-server-signed-certificates-for-public-client-identity-keys-id-cert) in PEM format.")
44+
@example("------BEGIN CERTIFICATE------...")
45+
id_cert: string;
46+
47+
@doc("An authorization secret, called a \"session token\", valid for this `id_cert`/session.")
48+
token: string;
49+
};
4450
};
4551

46-
@route("/session/keymaterial")
47-
@summary("Upload encrypted private key material")
48-
@added(Version.`v1.0-alpha.1`)
49-
@post
5052
/**
5153
* Upload encrypted private key material to the server for later retrieval. The size of
52-
* the individual array elements must not exceed
53-
* the server's maximum upload size for this route. This is usually not more than 10kb and can be as
54+
* the individual array elements must not exceed
55+
* the server's maximum upload size for this route. This is usually not more than 10kb and can be as
5456
* low as 800 bytes, depending on the server configuration.
5557
* @param pkm Array of encrypted private key material objects.
5658
*/
57-
op uploadEncryptedPKM(@body @minItems(1) pkm:
58-
polyproto.core.models.EncryptedPKM[]): {
59-
@statusCode statusCode: 201;
60-
} | {
61-
@doc("Used, if the `serial_number` does not match any known ID-Cert from this actor.")
62-
@statusCode statusCode: 404;
63-
} | {
64-
@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.")
65-
@statusCode statusCode: 409;
66-
} | {
67-
@doc("Uploaded key material exceeds the server's maximum upload size.")
68-
@statusCode statusCode: 413;
69-
};
70-
7159
@route("/session/keymaterial")
72-
@summary("Get encrypted private key material")
60+
@summary("Upload encrypted private key material")
7361
@added(Version.`v1.0-alpha.1`)
74-
@get
62+
@post
63+
op uploadEncryptedPKM(
64+
@body @minItems(1) pkm: polyproto.core.models.EncryptedPKM[],
65+
):
66+
| {
67+
@statusCode statusCode: 201;
68+
}
69+
| {
70+
@doc("Used, if the `serial_number` does not match any known ID-Cert from this actor.")
71+
@statusCode
72+
statusCode: 404;
73+
}
74+
| {
75+
@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.")
76+
@statusCode
77+
statusCode: 409;
78+
}
79+
| {
80+
@doc("Uploaded key material exceeds the server's maximum upload size.")
81+
@statusCode
82+
statusCode: 413;
83+
};
84+
7585
/**
7686
* Retrieve encrypted private key material from the server. The `serial_numbers`, if
7787
* provided, must match the serial numbers of ID-Certs that the client has uploaded key
7888
* material for. If no `serial_numbers` are provided, the server will return all key
7989
* material that the client has uploaded.
8090
*/
91+
@route("/session/keymaterial")
92+
@summary("Get encrypted private key material")
93+
@added(Version.`v1.0-alpha.1`)
94+
@get
8195
op getEncryptedPKM(@query serials?: uint64[]): {
8296
@statusCode statusCode: 200;
8397
@body encryptedPKMs: polyproto.core.models.EncryptedPKM[];
8498
} | {
8599
@doc("Returned, if no `serial_numbers` are provided and the client has not uploaded any key material.")
86-
@statusCode statusCode: 204;
87-
@header({name: "Content-Length"}) contentLength: 0;
100+
@statusCode
101+
statusCode: 204;
102+
103+
@header({
104+
name: "Content-Length",
105+
})
106+
contentLength: 0;
88107
} | {
89108
@doc("Returned, if none of the `serial_numbers` match any known ID-Certs from this actor.")
90-
@statusCode statusCode: 404;
109+
@statusCode
110+
statusCode: 404;
91111
};
92112

113+
/**
114+
* Delete encrypted private key material from the server. The `serial_number(s)`, must match
115+
* the serial numbers of ID-Certs that the client has uploaded key material for.
116+
*/
93117
@route("/session/keymaterial")
94118
@tag("Sensitive Actions")
95119
@summary("Delete encrypted private key material")
96120
@added(Version.`v1.0-alpha.1`)
97121
@delete
98-
/**
99-
* Delete encrypted private key material from the server. The `serial_number(s)`, must match
100-
* the serial numbers of ID-Certs that the client has uploaded key material for.
101-
*/
102122
op deleteEncryptedPKM(
103123
@doc("Sensitive actions require a second factor of authentication to be executed. Read [section 4.1.2 of the protocol definition](https://docs.polyphony.chat/Protocol%20Specifications/core/#412-sensitive-actions) for more information.")
104-
@header({name: "X-P2-Sensitive-Solution"}) sensitiveSolution: string,
105-
@query serials: uint64[]): {
124+
@header({
125+
name: "X-P2-Sensitive-Solution",
126+
})
127+
sensitiveSolution: string,
128+
129+
@query serials: uint64[],
130+
): {
106131
@statusCode statusCode: 204;
107-
@header({name: "Content-Length"}) contentLength: 0;
132+
@header({
133+
name: "Content-Length",
134+
})
135+
contentLength: 0;
108136
} | {
109137
@doc("Returned, if none of the `serial_numbers` match any known ID-Certs from this actor.")
110-
@statusCode statusCode: 404;
138+
@statusCode
139+
statusCode: 404;
111140
};
112-
141+
142+
/**
143+
* Retrieve the maximum upload size for encrypted private key material, in bytes.
144+
*
145+
* @returns The upload size limit, in bytes.
146+
*/
113147
@route("/session/keymaterial/size")
114148
@summary("Get encrypted private key material upload size limit")
115149
@added(Version.`v1.0-alpha.1`)
116150
@get
117151
@useAuth(NoAuth)
118-
/**
119-
* Retrieve the maximum upload size for encrypted private key material, in bytes.
120-
*
121-
* @returns The upload size limit, in bytes.
122-
*/
123152
op encryptedPKMsizeLimit(): {
124-
@header({name: "X-MAX-PAYLOAD-SIZE"}) size: uint32;
153+
@header({
154+
name: "X-MAX-PAYLOAD-SIZE",
155+
})
156+
size: uint32;
125157
@statusCode statusCode: 200;
126158
};
127159

160+
/**
161+
* Invalidate a session and its' associated ID-Cert by providing the session ID associated
162+
* with it.
163+
*/
128164
@route("/session")
129165
@delete
130166
@added(Version.`v1.0-alpha.1`)
131167
@summary("Delete/Revoke Session")
132168
@useAuth(BearerAuth)
133-
/**
134-
* Invalidate a session and its' associated ID-Cert by providing the session ID associated
135-
* with it.
136-
*/
137169
op deleteSession(
138170
@doc("Sensitive actions require a second factor of authentication to be executed. Read [section 4.1.2 of the protocol definition](https://docs.polyphony.chat/Protocol%20Specifications/core/#412-sensitive-actions) for more information.")
139-
@header({name: "X-P2-Sensitive-Solution"}) sensitiveSolution: string,
140-
@query session_id: string
141-
): {
171+
@header({
172+
name: "X-P2-Sensitive-Solution",
173+
})
174+
sensitiveSolution: string,
175+
176+
@query session_id: string,
177+
): {
142178
@statusCode statusCode: 204;
143-
@header({name: "Content-Length"}) contentLength: 0;
179+
@header({
180+
name: "Content-Length",
181+
})
182+
contentLength: 0;
144183
} | {
145184
@statusCode statusCode: 404;
146185
};
147186

187+
/**
188+
* Rotate the server's identity key. Requires server administrator permissions.
189+
* @returns The servers' new ID-Cert, encoded as PEM
190+
*/
148191
@route("/key/server")
149192
@summary("Rotate Server Identity Key")
150193
@added(Version.`v1.0-alpha.1`)
151194
@post
152195
@useAuth(BearerAuth)
153196
@tag("Sensitive Actions")
154-
/**
155-
* Rotate the server's identity key. Requires server administrator permissions.
156-
* @returns The servers' new ID-Cert, encoded as PEM
157-
*/
158-
op name(@doc("Sensitive actions require a second factor of authentication to be executed. Read [section 4.1.2 of the protocol definition](https://docs.polyphony.chat/Protocol%20Specifications/core/#412-sensitive-actions) for more information.")
159-
@header({name: "X-P2-Sensitive-Solution"}) sensitiveSolution: string,): string;
197+
op name(
198+
@doc("Sensitive actions require a second factor of authentication to be executed. Read [section 4.1.2 of the protocol definition](https://docs.polyphony.chat/Protocol%20Specifications/core/#412-sensitive-actions) for more information.")
199+
@header({
200+
name: "X-P2-Sensitive-Solution",
201+
})
202+
sensitiveSolution: string,
203+
): string;
160204
}
161205

162206
@tag("Federated Identity - Registration not required")
163207
namespace Unregistered {
164-
@route("/challenge")
165-
@summary("Receive a challenge string")
166-
@useAuth(BearerAuth)
167-
@added(Version.`v1.0-alpha.1`)
168-
@get
169-
/**
170-
* Request a challenge string. See the corresponding
171-
* [protocol definition chapter](https://docs.polyphony.chat/Protocol%20Specifications/core/#42-challenge-strings)
172-
* for more information.
173-
*/
174-
op challengeString(): {
175-
@statusCode statusCode: 200;
176-
@body challengeStringResponse: polyproto.core.models.ChallengeStringResponse
177-
};
178-
179-
@route("/idcert/server")
180-
@get
181-
@added(Version.`v1.0-alpha.1`)
182-
@summary("Get Server ID-Cert")
183208
/**
184209
* Request the server's public identity certificate.
185210
* @returns The current ID-Cert of the server, or, if specified, the ID-Cert the server had
186211
* at the specified time.
187212
* @param timestamp An optional UNIX timestamp to retrieve the ID-Cert the server had at that
188213
* point in time, instead of the current one.
189214
*/
190-
op serverIdCert(@query timestamp?: uint64): polyproto.core.models.CacheableIDCert;
191-
192-
@route("/idcert/actor")
215+
@route("/idcert/server")
193216
@get
194217
@added(Version.`v1.0-alpha.1`)
195-
@summary("Get Actor ID-Cert(s)")
218+
@summary("Get Server ID-Cert")
219+
op serverIdCert(
220+
@query timestamp?: uint64,
221+
): polyproto.core.models.CacheableIDCert;
222+
196223
/**
197224
* Request the ID-Certs of a specific actor. The specified actor must be registered on this server.
198225
* @param fid The ID of the actor whose ID-Cert(s) should be returned.
199226
* @param notBefore: Return only ID-Certs from at or after a specific point in time. UNIX 64 bit timestamp.
200227
* @param notAfter: Return only ID-Certs from at or before a specific point in time. UNIX 64 bit timestamp.
201228
* @param session_id Optionally, return only the ID-Certs matching a specific `session_id`.
202229
* @returns JSON-Array of Object(s).
203-
*/
204-
op actorCerts(@path fid: string, @query notBefore?: uint64, @query notAfter?: uint64, @query session_id?: string): {
230+
*/
231+
@route("/idcert/actor")
232+
@get
233+
@added(Version.`v1.0-alpha.1`)
234+
@summary("Get Actor ID-Cert(s)")
235+
op actorCerts(
236+
@path fid: string,
237+
@query notBefore?: uint64,
238+
@query notAfter?: uint64,
239+
@query session_id?: string,
240+
): {
205241
@statusCode statusCode: 200;
206-
@body response: polyproto.core.models.CacheableIDCert[]
242+
@body response: polyproto.core.models.CacheableIDCert[];
207243
};
208244

209-
@route("/session/idcert/extern")
210-
@put
211-
@added(Version.`v1.0-alpha.1`)
212-
@useAuth(BearerAuth)
213-
@summary("Update session ID-Cert")
214245
/**
215246
* Lets a foreign server know that the ID-Cert of a session has changed. This route is also
216247
* used to inform foreign servers about the revocation of an ID-Cert. The ID-Cert passed as
217248
* body in this route must belong to the actor making the request.
218249
* @returns 201 on success, 400 if the body is somehow invalid.
219250
*/
251+
@route("/session/idcert/extern")
252+
@put
253+
@added(Version.`v1.0-alpha.1`)
254+
@useAuth(BearerAuth)
255+
@summary("Update session ID-Cert")
220256
op updateSessionCert(@body id_cert: string): {
221257
@statusCode statusCode: 201;
222258
} | {

0 commit comments

Comments
 (0)