Mercurial

comparison connectors/connector.h @ 279:b3b547563ec7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add Google connector service and agent wiki Implement the C/Seobeo Google Drive and Gmail connector with encrypted OAuth storage, Zenbu authentication, browser testing, AI tool discovery, chunked HTTP decoding, and Bazel coverage. Consolidate repository guidance into progressive wiki documentation and enforce arena-first allocation for new first-party C code. Co-authored-by: Copilot <[email protected]> Copilot-Session: 84c338fd-0939-4bb3-b7f3-1062eb213e5d
author MrJuneJune <me@mrjunejune.com>
date Mon, 17 Aug 2026 22:22:36 -0700
parents
children
comparison
equal deleted inserted replaced
278:8d560f50ed4c 279:b3b547563ec7
1 #ifndef ZENBU_CONNECTOR_H
2 #define ZENBU_CONNECTOR_H
3
4 #include "deita/deita.h"
5 #include "dowa/dowa.h"
6 #include "seobeo/seobeo.h"
7
8 #include <stddef.h>
9
10 #define CONNECTOR_MAX_JSON_BYTES (1024 * 1024)
11 #define CONNECTOR_ID_MAX 128
12
13 typedef enum {
14 CONNECTOR_OK = 0,
15 CONNECTOR_ERROR,
16 CONNECTOR_INVALID,
17 CONNECTOR_NOT_FOUND,
18 CONNECTOR_FORBIDDEN,
19 CONNECTOR_CONFIRMATION_REQUIRED,
20 CONNECTOR_CONFLICT,
21 CONNECTOR_PROVIDER_ERROR
22 } Connector_Status;
23
24 typedef enum {
25 CONNECTOR_CONFIRM_NEVER = 0,
26 CONNECTOR_CONFIRM_ALWAYS = 1
27 } Connector_Confirmation_Policy;
28
29 typedef enum {
30 CONNECTOR_OP_DRIVE_LIST,
31 CONNECTOR_OP_DRIVE_GET,
32 CONNECTOR_OP_DRIVE_DOWNLOAD,
33 CONNECTOR_OP_DRIVE_CHANGES,
34 CONNECTOR_OP_DRIVE_CREATE,
35 CONNECTOR_OP_DRIVE_UPLOAD,
36 CONNECTOR_OP_DRIVE_UPDATE,
37 CONNECTOR_OP_GMAIL_LIST,
38 CONNECTOR_OP_GMAIL_GET,
39 CONNECTOR_OP_GMAIL_ATTACHMENT,
40 CONNECTOR_OP_GMAIL_HISTORY,
41 CONNECTOR_OP_GMAIL_DRAFT_CREATE,
42 CONNECTOR_OP_GMAIL_SEND
43 } Connector_Operation;
44
45 typedef struct {
46 uint32 version;
47 uint8 key[32];
48 } Connector_Master_Key;
49
50 typedef struct {
51 char account_id[CONNECTOR_ID_MAX];
52 char user_id[CONNECTOR_ID_MAX];
53 char provider[32];
54 char provider_subject[CONNECTOR_ID_MAX];
55 char email[256];
56 char access_token[2048];
57 char refresh_token[2048];
58 int64 expires_at;
59 char scopes[1024];
60 } Connector_Account;
61
62 typedef struct {
63 char account_id[CONNECTOR_ID_MAX];
64 char provider[32];
65 char email[256];
66 int64 expires_at;
67 char scopes[1024];
68 } Connector_Account_Summary;
69
70 typedef struct {
71 char state[128];
72 char code_verifier[128];
73 char code_challenge[128];
74 } Connector_OAuth_Start;
75
76 typedef struct {
77 const char *method;
78 const char *url;
79 const char *content_type;
80 const char *body;
81 size_t body_length;
82 const char *download_path;
83 } Connector_HTTP_Request;
84
85 typedef struct {
86 int32 status_code;
87 char *body;
88 size_t body_length;
89 } Connector_HTTP_Response;
90
91 typedef struct {
92 int32 http_status;
93 char code[64];
94 char description[256];
95 } Connector_Provider_Error;
96
97 typedef Connector_Status (*Connector_HTTP_Transport)(
98 const Connector_HTTP_Request *request,
99 const char *access_token,
100 Connector_HTTP_Response *response,
101 Dowa_Arena *arena,
102 void *context);
103
104 typedef struct {
105 const char *client_id;
106 const char *client_secret;
107 const char *redirect_uri;
108 const char *oauth_authorize_url;
109 const char *oauth_token_url;
110 const char *oauth_revoke_url;
111 const char *identity_url;
112 const char *drive_api_url;
113 const char *drive_upload_url;
114 const char *gmail_api_url;
115 Connector_HTTP_Transport transport;
116 void *transport_context;
117 } Connector_Google_Config;
118
119 typedef struct {
120 const char *method;
121 const char *path;
122 const char *query;
123 const char *content_type;
124 const char *body;
125 size_t body_length;
126 const char *download_path;
127 boolean overwrite;
128 } Connector_Provider_Request;
129
130 typedef struct {
131 Connector_Status status;
132 int32 provider_status;
133 char *body;
134 size_t body_length;
135 } Connector_Provider_Response;
136
137 typedef struct Connector_Store {
138 Deita_Connection *connection;
139 Connector_Master_Key master_key;
140 } Connector_Store;
141
142 typedef const char *(*Connector_Auth_Resolve_User)(
143 Seobeo_Request_Entry *request,
144 boolean require_csrf,
145 Dowa_Arena *arena,
146 void *context);
147
148 typedef struct {
149 char user_id[CONNECTOR_ID_MAX];
150 char username[64];
151 char role[16];
152 char csrf_token[128];
153 } Connector_Auth_Session;
154
155 typedef boolean (*Connector_Auth_Resolve_Session)(
156 Seobeo_Request_Entry *request,
157 Connector_Auth_Session *session,
158 void *context);
159
160 typedef struct {
161 Connector_Auth_Resolve_User resolve_user;
162 Connector_Auth_Resolve_Session resolve_session;
163 void *context;
164 } Connector_Auth_Adapter;
165
166 boolean Connector_Base64Url_Encode(
167 const uint8 *input, size_t input_length, char *output, size_t output_size);
168 boolean Connector_Base64Url_Decode(
169 const char *input, uint8 *output, size_t output_size, size_t *output_length);
170 boolean Connector_Encrypt(
171 const Connector_Master_Key *key, const char *plaintext,
172 char *encoded, size_t encoded_size);
173 boolean Connector_Decrypt(
174 const Connector_Master_Key *key, const char *encoded,
175 char *plaintext, size_t plaintext_size);
176 boolean Connector_Form_Encode(
177 const char *input, char *output, size_t output_size);
178 boolean Connector_Request_Digest(
179 const char *user_id, const char *account_id, Connector_Operation operation,
180 const Connector_Provider_Request *request, char output[65]);
181 boolean Connector_OAuth_PKCE_Start(Connector_OAuth_Start *start);
182 const char *Connector_Operation_Name(Connector_Operation operation);
183 boolean Connector_Operation_Is_Mutation(Connector_Operation operation);
184 boolean Connector_Operation_Is_Allowed(Connector_Operation operation);
185
186 boolean Connector_Store_Open(
187 Connector_Store *store, const char *database_path,
188 const Connector_Master_Key *master_key);
189 void Connector_Store_Close(Connector_Store *store);
190 boolean Connector_Store_Migrate(Connector_Store *store);
191 boolean Connector_Store_Create_State(
192 Connector_Store *store, const char *user_id, const Connector_OAuth_Start *start,
193 int64 expires_at);
194 boolean Connector_Store_Consume_State(
195 Connector_Store *store, const char *user_id, const char *state, int64 now,
196 char *verifier, size_t verifier_size);
197 boolean Connector_Store_Save_Account(
198 Connector_Store *store, const Connector_Account *account);
199 boolean Connector_Store_Get_Account(
200 Connector_Store *store, const char *user_id, const char *account_id,
201 Connector_Account *account);
202 boolean Connector_Store_List_Accounts(
203 Connector_Store *store, const char *user_id,
204 Connector_Account_Summary **accounts, Dowa_Arena *arena);
205 boolean Connector_Store_Delete_Account(
206 Connector_Store *store, const char *user_id, const char *account_id);
207 boolean Connector_Store_Set_Policy(
208 Connector_Store *store, const char *user_id, const char *action,
209 Connector_Confirmation_Policy policy);
210 Connector_Confirmation_Policy Connector_Store_Get_Policy(
211 Connector_Store *store, const char *user_id, const char *action);
212 boolean Connector_Store_Create_Confirmation(
213 Connector_Store *store, const char *user_id, const char *digest,
214 const char *token, int64 expires_at);
215 boolean Connector_Store_Consume_Confirmation(
216 Connector_Store *store, const char *user_id, const char *digest,
217 const char *token, int64 now);
218 boolean Connector_Store_Get_Idempotent(
219 Connector_Store *store, const char *user_id, const char *key,
220 const char *digest, int32 *status, char *body, size_t body_size);
221 boolean Connector_Store_Idempotency_Conflict(
222 Connector_Store *store, const char *user_id, const char *key,
223 const char *digest);
224 boolean Connector_Store_Put_Idempotent(
225 Connector_Store *store, const char *user_id, const char *key,
226 const char *digest, int32 status, const char *body);
227 boolean Connector_Store_Audit(
228 Connector_Store *store, const char *user_id, const char *account_id,
229 const char *operation, const char *digest, int32 status);
230
231 char *Connector_Google_Authorization_URL(
232 const Connector_Google_Config *config, const Connector_OAuth_Start *start,
233 Dowa_Arena *arena);
234 Connector_Status Connector_Google_Exchange_Code(
235 const Connector_Google_Config *config, const char *code,
236 const char *verifier, Connector_Account *account,
237 Connector_Provider_Error *error, Dowa_Arena *arena);
238 Connector_Status Connector_Google_Refresh(
239 const Connector_Google_Config *config, Connector_Account *account,
240 Dowa_Arena *arena);
241 Connector_Status Connector_Google_Revoke(
242 const Connector_Google_Config *config, const char *token, Dowa_Arena *arena);
243 Connector_Status Connector_Google_Execute(
244 const Connector_Google_Config *config, Connector_Operation operation,
245 const Connector_Provider_Request *request, const char *access_token,
246 Connector_Provider_Response *response, Dowa_Arena *arena);
247
248 void Connector_Service_Configure(
249 Connector_Store *store, const Connector_Google_Config *google,
250 Connector_Auth_Adapter auth);
251 void Connector_Service_Register_Routes(void);
252
253 #endif