@ixo/action-protocol 0.0.0-stage → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/index.js ADDED
@@ -0,0 +1,1190 @@
1
+ import {
2
+ operationJsonSchema,
3
+ operationKinds,
4
+ validateOperationSchema,
5
+ } from "./operation-schema.js";
6
+ export { operationJsonSchema, operationKinds };
7
+ const ID = /^[A-Za-z0-9_-]{32}$/;
8
+ const HEX = /^[a-f0-9]{64}$/;
9
+ const ADDRESS = /^ixo1[023456789acdefghjklmnpqrstuvwxyz]{38,59}$/;
10
+ const INT = /^(0|[1-9][0-9]*)$/;
11
+ const FIELD = /^[a-z][a-z0-9_]{0,39}$/;
12
+ /** Envelope tags. v1 carries only the 0.1 status/receipt set; v2 adds terminal non-execution outcomes. */
13
+ export const OUTCOME_VERSION_V1 = "ixo.auth-outcome/1";
14
+ export const OUTCOME_VERSION_V2 = "ixo.auth-outcome/2";
15
+ export const CAPABILITIES_VERSION_V1 = "ixo.auth-capabilities/1";
16
+ export const CAPABILITIES_VERSION_V2 = "ixo.auth-capabilities/2";
17
+ const MEMO_BYTES = 256;
18
+ /** 0.2.1: mainnet is a valid network value; enablement is a Hub deployment decision. */
19
+ export const NETWORKS = ["ixo mainnet", "ixo testnet", "ixo devnet"];
20
+ /**
21
+ * 0.4.1: authorization / statement-proof `network` (bare names). Every ixo
22
+ * network is valid; the receiver must require its own deployment's network.
23
+ */
24
+ export const SERVICE_NETWORKS = ["mainnet", "testnet", "devnet"];
25
+ const V1_OUTCOME_STATUSES = [
26
+ "authorized",
27
+ "declined",
28
+ "submitted",
29
+ "succeeded",
30
+ "failed",
31
+ "unknown",
32
+ ];
33
+ /** The 0.1.0 receipt and operation sets: the only ones a v1 envelope may carry. */
34
+ const V1_RECEIPT_KINDS = ["form.submission.v1", "ixo.bank.send.v1"];
35
+ export const V1_OPERATION_KINDS = [
36
+ "form.submit.v1",
37
+ "ixo.bank.send.v1",
38
+ "resource.read.v1",
39
+ ];
40
+ /** Terminal outcomes for an action that never executed (v2 only, receipt always null). */
41
+ const V2_ONLY_OUTCOME_STATUSES = ["expired", "cancelled"];
42
+ export const OUTCOME_SEQUENCE = {
43
+ authorized: 1,
44
+ declined: 1,
45
+ submitted: 2,
46
+ unknown: 3,
47
+ succeeded: 4,
48
+ failed: 4,
49
+ expired: 5,
50
+ cancelled: 5,
51
+ };
52
+ /** A transfer that was signed but never included in a block (`height` is null). */
53
+ export const BANK_NOT_INCLUDED_REASONS = [
54
+ "check_tx_rejected",
55
+ "expired_not_included",
56
+ ];
57
+ const fail = (field) => {
58
+ throw new TypeError(`Invalid ${field}`);
59
+ };
60
+ const object = (value, field) =>
61
+ value && typeof value === "object" && !Array.isArray(value)
62
+ ? value
63
+ : fail(field);
64
+ const exact = (value, keys, field) => {
65
+ for (const key of Object.keys(value)) if (!keys.includes(key)) fail(field);
66
+ };
67
+ const str = (value, field, min = 1, max = 200) =>
68
+ typeof value === "string" && value.length >= min && value.length <= max
69
+ ? value
70
+ : fail(field);
71
+ const num = (value, field) =>
72
+ Number.isSafeInteger(value) && value > 0 ? value : fail(field);
73
+ const pattern = (value, regex, field) =>
74
+ regex.test(str(value, field)) ? value : fail(field);
75
+
76
+ export function canonicalJson(value) {
77
+ if (value === null || typeof value === "string" || typeof value === "boolean")
78
+ return JSON.stringify(value);
79
+ if (typeof value === "number" && Number.isSafeInteger(value))
80
+ return JSON.stringify(value);
81
+ if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
82
+ if (
83
+ value &&
84
+ typeof value === "object" &&
85
+ Object.getPrototypeOf(value) === Object.prototype
86
+ ) {
87
+ const keys = Object.keys(value).sort();
88
+ return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
89
+ }
90
+ return fail("canonical JSON");
91
+ }
92
+
93
+ export async function digestOf(value) {
94
+ const bytes = new TextEncoder().encode(canonicalJson(value));
95
+ const hash = await crypto.subtle.digest("SHA-256", bytes);
96
+ return Array.from(new Uint8Array(hash), (byte) =>
97
+ byte.toString(16).padStart(2, "0"),
98
+ ).join("");
99
+ }
100
+
101
+ export function parseOperation(input) {
102
+ const op = object(input, "operation");
103
+ validateOperationSchema(op);
104
+ if (op.kind === "statement.sign.v1") {
105
+ utf8(op.statement, "statement");
106
+ return op;
107
+ }
108
+ if (op.kind === "vfs.text.save.v1") {
109
+ utf8(op.text, "text");
110
+ privateTextPath("A".repeat(32), op.filename);
111
+ return op;
112
+ }
113
+ if (op.kind.startsWith("gmail.")) {
114
+ for (const field of [
115
+ "accountLabel",
116
+ ...(op.kind === "gmail.message.send.v1" ? ["to"] : []),
117
+ ]) {
118
+ if (op[field] !== null && op[field].split("@")[0].length > 64)
119
+ fail(field);
120
+ }
121
+ if (op.kind === "gmail.message.send.v1") {
122
+ utf8(op.subject, "subject");
123
+ utf8(op.body, "body");
124
+ }
125
+ return op;
126
+ }
127
+ if (op.kind === "calendar.event.create.v1") {
128
+ if (!validCalendarInstant(op.startsAt) || !validCalendarInstant(op.endsAt))
129
+ fail("calendar instant");
130
+ const start = Date.parse(op.startsAt),
131
+ end = Date.parse(op.endsAt);
132
+ if (
133
+ !Number.isFinite(start) ||
134
+ !Number.isFinite(end) ||
135
+ end <= start ||
136
+ end - start > 86400000
137
+ )
138
+ fail("event duration");
139
+ try {
140
+ new Intl.DateTimeFormat("en", { timeZone: op.timeZone });
141
+ } catch {
142
+ fail("timeZone");
143
+ }
144
+ return op;
145
+ }
146
+ if (
147
+ [
148
+ "calendar.connect.v1",
149
+ "calendar.disconnect.v1",
150
+ "vfs.access.request.v1",
151
+ ].includes(op.kind)
152
+ )
153
+ return op;
154
+ if (op.kind === "form.submit.v1") {
155
+ exact(
156
+ op,
157
+ ["kind", "formId", "destination", "fields", "declaration"],
158
+ "operation",
159
+ );
160
+ str(op.formId, "formId", 1, 120);
161
+ str(op.destination, "destination", 1, 200);
162
+ if (
163
+ !Array.isArray(op.fields) ||
164
+ op.fields.length < 1 ||
165
+ op.fields.length > 20
166
+ )
167
+ fail("fields");
168
+ const ids = new Set();
169
+ for (const field of op.fields) {
170
+ object(field, "field");
171
+ exact(
172
+ field,
173
+ ["id", "label", "type", "required", "value", "source"],
174
+ "field",
175
+ );
176
+ pattern(field.id, FIELD, "field.id");
177
+ if (ids.has(field.id)) fail("duplicate field");
178
+ ids.add(field.id);
179
+ str(field.label, "field.label", 1, 120);
180
+ if (!["text", "email", "tel", "textarea"].includes(field.type))
181
+ fail("field.type");
182
+ if (typeof field.required !== "boolean") fail("field.required");
183
+ str(field.value, "field.value", 0, 1000);
184
+ if (!["user", "record", "suggestion"].includes(field.source))
185
+ fail("field.source");
186
+ }
187
+ if (op.declaration !== null) str(op.declaration, "declaration", 1, 120);
188
+ return op;
189
+ }
190
+ if (op.kind === "ixo.bank.send.v1") {
191
+ exact(
192
+ op,
193
+ [
194
+ "kind",
195
+ "chainId",
196
+ "network",
197
+ "fromAddress",
198
+ "toAddress",
199
+ "amountBaseUnits",
200
+ "denom",
201
+ "feeBaseUnits",
202
+ "memo",
203
+ ],
204
+ "operation",
205
+ );
206
+ str(op.chainId, "chainId", 1, 100);
207
+ // Every ixo network is expressible; a Hub executes only its own chain.
208
+ if (!NETWORKS.includes(op.network)) fail("network");
209
+ pattern(op.fromAddress, ADDRESS, "fromAddress");
210
+ pattern(op.toAddress, ADDRESS, "toAddress");
211
+ if (op.fromAddress === op.toAddress) fail("self transfer");
212
+ pattern(op.amountBaseUnits, INT, "amountBaseUnits");
213
+ if (op.amountBaseUnits === "0") fail("amountBaseUnits");
214
+ if (op.denom !== "uixo") fail("denom");
215
+ pattern(op.feeBaseUnits, INT, "feeBaseUnits");
216
+ str(op.memo, "memo", 0, 256);
217
+ // Cosmos SDK x/auth max_memo_characters counts UTF-8 bytes, not UTF-16 units.
218
+ if (new TextEncoder().encode(op.memo).length > MEMO_BYTES) fail("memo");
219
+ return op;
220
+ }
221
+ if (op.kind === "resource.read.v1") {
222
+ exact(
223
+ op,
224
+ ["kind", "resourceId", "ownerDid", "url", "version", "contentDigest"],
225
+ "operation",
226
+ );
227
+ str(op.resourceId, "resourceId", 1, 200);
228
+ str(op.ownerDid, "ownerDid", 1, 200);
229
+ const url = new URL(str(op.url, "resource.url", 1, 2000));
230
+ if (url.protocol !== "https:" || url.username || url.password || url.hash)
231
+ fail("resource.url");
232
+ str(op.version, "resource.version", 1, 200);
233
+ pattern(op.contentDigest, HEX, "resource.contentDigest");
234
+ return op;
235
+ }
236
+ return fail("operation.kind");
237
+ }
238
+
239
+ export function parseReference(input) {
240
+ const ref = object(input, "reference");
241
+ exact(
242
+ ref,
243
+ [
244
+ "version",
245
+ "id",
246
+ "accountId",
247
+ "bindingId",
248
+ "bindingRevision",
249
+ "revision",
250
+ "digest",
251
+ "url",
252
+ "expiresAt",
253
+ "title",
254
+ ],
255
+ "reference",
256
+ );
257
+ if (ref.version !== "ixo.auth-action/1") fail("reference.version");
258
+ pattern(ref.id, ID, "reference.id");
259
+ str(ref.accountId, "reference.accountId", 1, 100);
260
+ str(ref.bindingId, "reference.bindingId", 1, 100);
261
+ num(ref.bindingRevision, "reference.bindingRevision");
262
+ num(ref.revision, "reference.revision");
263
+ pattern(ref.digest, HEX, "reference.digest");
264
+ const url = new URL(str(ref.url, "reference.url", 1, 2000));
265
+ if (
266
+ !(
267
+ url.protocol === "https:" ||
268
+ (url.protocol === "http:" && url.hostname === "localhost")
269
+ ) ||
270
+ url.username ||
271
+ url.password ||
272
+ url.search ||
273
+ url.hash ||
274
+ url.pathname !== `/a/${ref.id}`
275
+ )
276
+ fail("reference.url");
277
+ num(ref.expiresAt, "reference.expiresAt");
278
+ str(ref.title, "reference.title", 1, 80);
279
+ return ref;
280
+ }
281
+
282
+ export function assertHubReferenceUrl(input, configuredOrigin) {
283
+ const ref = parseReference(input);
284
+ const configured = new URL(configuredOrigin);
285
+ if (
286
+ !(
287
+ configured.protocol === "https:" ||
288
+ (configured.protocol === "http:" && configured.hostname === "localhost")
289
+ ) ||
290
+ configured.pathname !== "/" ||
291
+ configured.search ||
292
+ configured.hash ||
293
+ new URL(ref.url).origin !== configured.origin
294
+ )
295
+ fail("reference.url.origin");
296
+ return ref;
297
+ }
298
+
299
+ export function parseReceipt(input) {
300
+ const receipt = object(input, "receipt");
301
+ if (p2ReceiptFields[receipt.kind]) return parseP2Receipt(receipt);
302
+ if (receipt.kind === "form.submission.v1") {
303
+ exact(
304
+ receipt,
305
+ [
306
+ "kind",
307
+ "actionId",
308
+ "revision",
309
+ "digest",
310
+ "valuesDigest",
311
+ "submittedAt",
312
+ "submissionId",
313
+ ],
314
+ "receipt",
315
+ );
316
+ pattern(receipt.actionId, ID, "receipt.actionId");
317
+ num(receipt.revision, "receipt.revision");
318
+ pattern(receipt.digest, HEX, "receipt.digest");
319
+ pattern(receipt.valuesDigest, HEX, "receipt.valuesDigest");
320
+ num(receipt.submittedAt, "receipt.submittedAt");
321
+ str(receipt.submissionId, "receipt.submissionId", 1, 100);
322
+ return receipt;
323
+ }
324
+ if (receipt.kind === "ixo.bank.send.v1") {
325
+ exact(
326
+ receipt,
327
+ [
328
+ "kind",
329
+ "actionId",
330
+ "revision",
331
+ "digest",
332
+ "chainId",
333
+ "txHash",
334
+ "height",
335
+ "code",
336
+ "reason",
337
+ ],
338
+ "receipt",
339
+ );
340
+ pattern(receipt.actionId, ID, "receipt.actionId");
341
+ num(receipt.revision, "receipt.revision");
342
+ pattern(receipt.digest, HEX, "receipt.digest");
343
+ str(receipt.chainId, "receipt.chainId", 1, 100);
344
+ pattern(receipt.txHash, HEX, "receipt.txHash");
345
+ if (receipt.height !== null) num(receipt.height, "receipt.height");
346
+ if (
347
+ receipt.code !== null &&
348
+ (!Number.isSafeInteger(receipt.code) || receipt.code < 0)
349
+ )
350
+ fail("receipt.code");
351
+ if ("reason" in receipt) {
352
+ if (
353
+ !BANK_NOT_INCLUDED_REASONS.includes(receipt.reason) ||
354
+ receipt.height !== null ||
355
+ (receipt.reason === "check_tx_rejected" &&
356
+ (receipt.code === null || receipt.code === 0)) ||
357
+ (receipt.reason === "expired_not_included" && receipt.code !== null)
358
+ )
359
+ fail("receipt.reason");
360
+ }
361
+ return receipt;
362
+ }
363
+ return fail("receipt.kind");
364
+ }
365
+
366
+ export function parseReviewView(input) {
367
+ const view = object(input, "view");
368
+ exact(
369
+ view,
370
+ [
371
+ "reference",
372
+ "requester",
373
+ "operation",
374
+ "reviewStatus",
375
+ "operationStatus",
376
+ "revision",
377
+ "digest",
378
+ "canEdit",
379
+ "canApprove",
380
+ "canSign",
381
+ "receipt",
382
+ "signedTxHash",
383
+ "resourceUrl",
384
+ "chatUrl",
385
+ "service",
386
+ ],
387
+ "view",
388
+ );
389
+ parseReference(view.reference);
390
+ if (view.service !== undefined && view.service !== null) {
391
+ object(view.service, "view.service");
392
+ exact(
393
+ view.service,
394
+ ["continuationUrl", "accountLabel", "resource"],
395
+ "view.service",
396
+ );
397
+ nullableUrl(view.service.continuationUrl);
398
+ nullableString(view.service.accountLabel, "accountLabel", 200);
399
+ if (view.service.resource !== null)
400
+ parseResourceDescriptor(view.service.resource);
401
+ }
402
+ str(view.requester, "view.requester", 1, 120);
403
+ parseOperation(view.operation);
404
+ if (
405
+ ![
406
+ "prepared",
407
+ "superseded",
408
+ "declined",
409
+ "expired",
410
+ "revoked",
411
+ "signing",
412
+ "authorized",
413
+ ].includes(view.reviewStatus)
414
+ )
415
+ fail("view.reviewStatus");
416
+ if (
417
+ ![
418
+ "awaiting_authorization",
419
+ "admitted",
420
+ "submitted",
421
+ "succeeded",
422
+ "failed",
423
+ "requires_review",
424
+ "unknown",
425
+ "not_started",
426
+ ].includes(view.operationStatus)
427
+ )
428
+ fail("view.operationStatus");
429
+ num(view.revision, "view.revision");
430
+ pattern(view.digest, HEX, "view.digest");
431
+ for (const key of ["canEdit", "canApprove", "canSign"])
432
+ if (typeof view[key] !== "boolean") fail(`view.${key}`);
433
+ if (view.receipt !== null) {
434
+ const receipt = parseReceipt(view.receipt);
435
+ if (
436
+ receipt.actionId !== view.reference.id ||
437
+ receipt.revision !== view.revision ||
438
+ receipt.digest !== view.digest
439
+ )
440
+ fail("view.receipt");
441
+ assertReceiptForOperation(view.operation, receipt, view.operationStatus);
442
+ if (
443
+ view.operation.kind === "form.submit.v1" &&
444
+ receipt.kind !== "form.submission.v1"
445
+ )
446
+ fail("view.receipt");
447
+ if (
448
+ view.operation.kind === "ixo.bank.send.v1" &&
449
+ receipt.kind !== "ixo.bank.send.v1"
450
+ )
451
+ fail("view.receipt");
452
+ if (!receiptFitsStatus(receipt, view.operationStatus)) fail("view.receipt");
453
+ }
454
+ if (
455
+ ["succeeded", "failed"].includes(view.operationStatus) &&
456
+ view.receipt === null
457
+ )
458
+ fail("view.receipt");
459
+ // `not_started`: terminal, nothing was executed (for example a decline).
460
+ if (view.operationStatus === "not_started" && view.receipt !== null)
461
+ fail("view.receipt");
462
+ if (view.signedTxHash !== null)
463
+ pattern(view.signedTxHash, HEX, "view.signedTxHash");
464
+ if (view.resourceUrl !== null) {
465
+ const url = new URL(str(view.resourceUrl, "view.resourceUrl", 1, 2000));
466
+ if (
467
+ !(
468
+ url.protocol === "https:" ||
469
+ (url.protocol === "http:" && url.hostname === "localhost")
470
+ ) ||
471
+ url.username ||
472
+ url.password ||
473
+ url.hash
474
+ )
475
+ fail("view.resourceUrl");
476
+ }
477
+ const chat = new URL(str(view.chatUrl, "view.chatUrl", 1, 2000));
478
+ if (chat.protocol !== "https:" || chat.username || chat.password)
479
+ fail("view.chatUrl");
480
+ return view;
481
+ }
482
+
483
+ export function parseOutcome(input) {
484
+ const outcome = object(input, "outcome");
485
+ exact(
486
+ outcome,
487
+ [
488
+ "version",
489
+ "eventId",
490
+ "reference",
491
+ "ownerDid",
492
+ "authorizedRevision",
493
+ "authorizedDigest",
494
+ "sequence",
495
+ "status",
496
+ "receipt",
497
+ "occurredAt",
498
+ ],
499
+ "outcome",
500
+ );
501
+ if (![OUTCOME_VERSION_V1, OUTCOME_VERSION_V2].includes(outcome.version))
502
+ fail("outcome.version");
503
+ const v2 = outcome.version === OUTCOME_VERSION_V2;
504
+ str(outcome.eventId, "outcome.eventId", 1, 100);
505
+ const ref = parseReference(outcome.reference);
506
+ str(outcome.ownerDid, "outcome.ownerDid", 1, 200);
507
+ num(outcome.authorizedRevision, "outcome.authorizedRevision");
508
+ pattern(outcome.authorizedDigest, HEX, "outcome.authorizedDigest");
509
+ num(outcome.sequence, "outcome.sequence");
510
+ if (
511
+ !V1_OUTCOME_STATUSES.includes(outcome.status) &&
512
+ !(v2 && V2_ONLY_OUTCOME_STATUSES.includes(outcome.status))
513
+ )
514
+ fail("outcome.status");
515
+ if (
516
+ ["succeeded", "failed"].includes(outcome.status) &&
517
+ outcome.receipt === null
518
+ )
519
+ fail("outcome.receipt");
520
+ if (outcome.receipt !== null) {
521
+ const receipt = parseReceipt(outcome.receipt);
522
+ if (
523
+ receipt.actionId !== ref.id ||
524
+ receipt.revision !== outcome.authorizedRevision ||
525
+ receipt.digest !== outcome.authorizedDigest
526
+ )
527
+ fail("outcome.receipt");
528
+ if (!receiptFitsStatus(receipt, outcome.status)) fail("outcome.receipt");
529
+ if (
530
+ !v2 &&
531
+ ("reason" in receipt || !V1_RECEIPT_KINDS.includes(receipt.kind))
532
+ )
533
+ fail("outcome.receipt");
534
+ }
535
+ if (
536
+ [
537
+ "authorized",
538
+ "declined",
539
+ "submitted",
540
+ "unknown",
541
+ ...V2_ONLY_OUTCOME_STATUSES,
542
+ ].includes(outcome.status) &&
543
+ outcome.receipt !== null
544
+ )
545
+ fail("outcome.receipt");
546
+ num(outcome.occurredAt, "outcome.occurredAt");
547
+ return outcome;
548
+ }
549
+
550
+ export function parseCapabilities(input) {
551
+ const data = object(input, "capabilities");
552
+ exact(
553
+ data,
554
+ [
555
+ "version",
556
+ "accountId",
557
+ "oracleDid",
558
+ "network",
559
+ "resourceOrigin",
560
+ "operations",
561
+ "forms",
562
+ "transfer",
563
+ ],
564
+ "capabilities",
565
+ );
566
+ if (
567
+ ![CAPABILITIES_VERSION_V1, CAPABILITIES_VERSION_V2].includes(data.version)
568
+ )
569
+ fail("capabilities.version");
570
+ str(data.accountId, "capabilities.accountId", 1, 100);
571
+ str(data.oracleDid, "capabilities.oracleDid", 1, 200);
572
+ if (
573
+ data.network !== null &&
574
+ !NETWORKS.includes(data.network)
575
+ )
576
+ fail("capabilities.network");
577
+ if (data.resourceOrigin !== null) {
578
+ const url = new URL(
579
+ str(data.resourceOrigin, "capabilities.resourceOrigin", 1, 2000),
580
+ );
581
+ if (
582
+ url.protocol !== "https:" ||
583
+ url.pathname !== "/" ||
584
+ url.search ||
585
+ url.hash
586
+ )
587
+ fail("capabilities.resourceOrigin");
588
+ }
589
+ if (
590
+ !Array.isArray(data.operations) ||
591
+ new Set(data.operations).size !== data.operations.length ||
592
+ data.operations.some(
593
+ (kind) =>
594
+ !(
595
+ data.version === CAPABILITIES_VERSION_V1
596
+ ? V1_OPERATION_KINDS
597
+ : operationKinds
598
+ ).includes(kind),
599
+ )
600
+ )
601
+ fail("capabilities.operations");
602
+ if (data.transfer !== null) {
603
+ object(data.transfer, "capabilities.transfer");
604
+ exact(
605
+ data.transfer,
606
+ ["maxAmountUixo", "maxFeeUixo"],
607
+ "capabilities.transfer",
608
+ );
609
+ pattern(
610
+ data.transfer.maxAmountUixo,
611
+ /^[1-9][0-9]{0,19}$/,
612
+ "capabilities.transfer.maxAmountUixo",
613
+ );
614
+ pattern(
615
+ data.transfer.maxFeeUixo,
616
+ /^[1-9][0-9]{0,19}$/,
617
+ "capabilities.transfer.maxFeeUixo",
618
+ );
619
+ }
620
+ if (data.operations.includes("ixo.bank.send.v1") && data.transfer === null)
621
+ fail("capabilities.transfer");
622
+ if (!Array.isArray(data.forms)) fail("capabilities.forms");
623
+ for (const form of data.forms) {
624
+ object(form, "capabilities.form");
625
+ exact(
626
+ form,
627
+ ["formId", "destination", "fields", "declaration"],
628
+ "capabilities.form",
629
+ );
630
+ str(form.formId, "formId", 1, 120);
631
+ str(form.destination, "destination", 1, 200);
632
+ if (form.declaration !== null) str(form.declaration, "declaration", 1, 120);
633
+ if (
634
+ !Array.isArray(form.fields) ||
635
+ form.fields.length < 1 ||
636
+ form.fields.length > 20
637
+ )
638
+ fail("form.fields");
639
+ const ids = new Set();
640
+ for (const field of form.fields) {
641
+ object(field, "field");
642
+ exact(field, ["id", "label", "type", "required"], "field");
643
+ pattern(field.id, FIELD, "field.id");
644
+ str(field.label, "field.label", 1, 120);
645
+ if (
646
+ !["text", "email", "tel", "textarea"].includes(field.type) ||
647
+ typeof field.required !== "boolean" ||
648
+ ids.has(field.id)
649
+ )
650
+ fail("field");
651
+ ids.add(field.id);
652
+ }
653
+ }
654
+ return data;
655
+ }
656
+
657
+ const utf8 = (value, field) => {
658
+ str(value, field, 0, 8192);
659
+ if (
660
+ new TextEncoder().encode(value).length > 8192 ||
661
+ /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(
662
+ value,
663
+ )
664
+ )
665
+ fail(field);
666
+ return value;
667
+ };
668
+ const nullableString = (v, f, max = 200) =>
669
+ v === null ? null : str(v, f, 1, max);
670
+ const urlValue = (v) => {
671
+ const u = new URL(str(v, "url", 1, 2000));
672
+ if (
673
+ (u.protocol !== "https:" &&
674
+ !(
675
+ u.protocol === "http:" &&
676
+ ["localhost", "127.0.0.1"].includes(u.hostname)
677
+ )) ||
678
+ u.username ||
679
+ u.password ||
680
+ u.hash
681
+ )
682
+ fail("url");
683
+ return v;
684
+ };
685
+ const nullableUrl = (v) => (v === null ? null : urlValue(v));
686
+ const scopeList = (v) => {
687
+ if (!Array.isArray(v) || v.length > 30 || new Set(v).size !== v.length)
688
+ fail("scopes");
689
+ for (const s of v) str(s, "scope", 1, 300);
690
+ return v;
691
+ };
692
+ const tuple = (v) => {
693
+ pattern(v.actionId, ID, "actionId");
694
+ num(v.revision, "revision");
695
+ pattern(v.digest, HEX, "digest");
696
+ };
697
+ export function privateTextPath(actionId, filename) {
698
+ pattern(actionId, ID, "actionId");
699
+ if (
700
+ typeof filename !== "string" ||
701
+ filename.length > 80 ||
702
+ !/^[A-Za-z0-9][A-Za-z0-9 _.-]*\.txt$/.test(filename) ||
703
+ filename.includes("..") ||
704
+ filename.endsWith(" .txt")
705
+ )
706
+ fail("filename");
707
+ return `/${actionId}-${filename}`;
708
+ }
709
+ export function serviceForOperation(op) {
710
+ const kind = typeof op === "string" ? op : op.kind;
711
+ return kind.startsWith("gmail.")
712
+ ? "gmail"
713
+ : kind.startsWith("calendar.")
714
+ ? "calendar"
715
+ : kind.startsWith("vfs.")
716
+ ? "vfs"
717
+ : null;
718
+ }
719
+ const receiptKinds = {
720
+ "form.submit.v1": "form.submission.v1",
721
+ "ixo.bank.send.v1": "ixo.bank.send.v1",
722
+ "statement.sign.v1": "statement.signed.v1",
723
+ "gmail.connect.v1": "gmail.connected.v1",
724
+ "gmail.disconnect.v1": "gmail.disconnected.v1",
725
+ "gmail.message.send.v1": "gmail.message.accepted.v1",
726
+ "calendar.connect.v1": "calendar.connected.v1",
727
+ "calendar.disconnect.v1": "calendar.disconnected.v1",
728
+ "calendar.event.create.v1": "calendar.event.created.v1",
729
+ "vfs.access.request.v1": "vfs.access.requested.v1",
730
+ "vfs.text.save.v1": "vfs.text.saved.v1",
731
+ };
732
+ export function assertReceiptForOperation(
733
+ operation,
734
+ receipt,
735
+ status = "succeeded",
736
+ ) {
737
+ parseReceipt(receipt);
738
+ if (
739
+ ["succeeded", "failed"].includes(status) &&
740
+ !receiptFitsStatus(receipt, status)
741
+ )
742
+ fail("operation receipt");
743
+ if (
744
+ status === "failed" &&
745
+ receipt.kind === "service.failure.v1" &&
746
+ receipt.service === serviceForOperation(operation)
747
+ )
748
+ return receipt;
749
+ if (
750
+ receiptKinds[operation.kind] !== receipt.kind ||
751
+ receipt.kind === "service.failure.v1"
752
+ )
753
+ fail("operation receipt");
754
+ // Every kind: the receipt must name the approved connection / target.
755
+ if (
756
+ "connectionId" in operation &&
757
+ operation.connectionId !== null &&
758
+ "connectionId" in receipt &&
759
+ receipt.connectionId !== operation.connectionId
760
+ )
761
+ fail("receipt connection");
762
+ if (
763
+ "targetId" in operation &&
764
+ "targetId" in receipt &&
765
+ receipt.targetId !== operation.targetId
766
+ )
767
+ fail("receipt target");
768
+ return receipt;
769
+ }
770
+ const p2ReceiptFields = {
771
+ "statement.signed.v1": [
772
+ "statementDigest",
773
+ "proofDigest",
774
+ "signerDid",
775
+ "signedAt",
776
+ ],
777
+ "gmail.connected.v1": ["connectionId", "scopesDigest", "verifiedAt"],
778
+ "gmail.disconnected.v1": [
779
+ "connectionId",
780
+ "localRevokedAt",
781
+ "providerDisconnected",
782
+ "verifiedAt",
783
+ ],
784
+ "gmail.message.accepted.v1": [
785
+ "connectionId",
786
+ "messageId",
787
+ "contentDigest",
788
+ "mimeDigest",
789
+ "acceptedAt",
790
+ ],
791
+ "calendar.connected.v1": ["connectionId", "scopesDigest", "verifiedAt"],
792
+ "calendar.disconnected.v1": [
793
+ "connectionId",
794
+ "localRevokedAt",
795
+ "providerDisconnected",
796
+ "verifiedAt",
797
+ ],
798
+ "calendar.event.created.v1": [
799
+ "connectionId",
800
+ "eventId",
801
+ "eventDigest",
802
+ "verifiedAt",
803
+ ],
804
+ "vfs.access.requested.v1": ["requestId", "targetId", "state", "requestedAt"],
805
+ "vfs.text.saved.v1": [
806
+ "fileId",
807
+ "cid",
808
+ "version",
809
+ "contentDigest",
810
+ "private",
811
+ "verifiedAt",
812
+ ],
813
+ "service.failure.v1": ["service", "code", "failedAt"],
814
+ };
815
+ function parseP2Receipt(v) {
816
+ exact(
817
+ v,
818
+ ["kind", "actionId", "revision", "digest", ...p2ReceiptFields[v.kind]],
819
+ "receipt",
820
+ );
821
+ tuple(v);
822
+ for (const k of p2ReceiptFields[v.kind]) {
823
+ if (k.endsWith("Digest")) pattern(v[k], HEX, k);
824
+ else if (k.endsWith("At") || k === "version") num(v[k], k);
825
+ else if (k === "private") {
826
+ if (v[k] !== true) fail(k);
827
+ } else if (k === "providerDisconnected") {
828
+ if (v[k] !== null && typeof v[k] !== "boolean") fail(k);
829
+ } else str(v[k], k, 1, k === "cid" ? 200 : 200);
830
+ }
831
+ if (v.kind === "vfs.access.requested.v1" && v.state !== "pending_owner")
832
+ fail("state");
833
+ if (
834
+ v.kind === "service.failure.v1" &&
835
+ (!["calendar", "gmail", "vfs"].includes(v.service) ||
836
+ ![
837
+ "permission_denied",
838
+ "changed",
839
+ "rejected",
840
+ "conflict",
841
+ // 0.4.0: expired before anything was sent; service unavailable.
842
+ "expired",
843
+ "unavailable",
844
+ ].includes(
845
+ v.code,
846
+ ))
847
+ )
848
+ fail("service failure");
849
+ return v;
850
+ }
851
+ export function parseResourceDescriptor(input) {
852
+ const v = object(input, "resource");
853
+ exact(
854
+ v,
855
+ [
856
+ "id",
857
+ "title",
858
+ "ownerDid",
859
+ "url",
860
+ "version",
861
+ "contentDigest",
862
+ "cid",
863
+ "fileId",
864
+ ],
865
+ "resource",
866
+ );
867
+ for (const k of ["id", "title", "ownerDid", "version", "cid", "fileId"])
868
+ str(v[k], k, 1, 200);
869
+ pattern(v.contentDigest, HEX, "contentDigest");
870
+ urlValue(v.url);
871
+ if (new URL(v.url).search) fail("resource.url");
872
+ return v;
873
+ }
874
+ export function parseServiceAuthorization(input) {
875
+ const v = object(input, "authorization");
876
+ exact(
877
+ v,
878
+ [
879
+ "version",
880
+ "mode",
881
+ "service",
882
+ "hubOrigin",
883
+ "accountId",
884
+ "actionId",
885
+ "ownerDid",
886
+ "oracleDid",
887
+ "bindingId",
888
+ "bindingRevision",
889
+ "consentVersion",
890
+ "policyVersion",
891
+ "revision",
892
+ "digest",
893
+ "network",
894
+ "operation",
895
+ "issuedAt",
896
+ "expiresAt",
897
+ "nonce",
898
+ ],
899
+ "authorization",
900
+ );
901
+ if (
902
+ v.version !== "ixo.auth-authorization/1" ||
903
+ !["prepare", "execute"].includes(v.mode) ||
904
+ !["calendar", "gmail", "vfs"].includes(v.service) ||
905
+ !SERVICE_NETWORKS.includes(v.network)
906
+ )
907
+ fail("authorization");
908
+ tuple(v);
909
+ for (const k of ["accountId", "bindingId", "consentVersion", "nonce"])
910
+ str(v[k], k, 1, 100);
911
+ for (const k of ["ownerDid", "oracleDid"]) str(v[k], k, 1, 200);
912
+ for (const k of ["bindingRevision", "policyVersion", "issuedAt", "expiresAt"])
913
+ num(v[k], k);
914
+ if (v.expiresAt <= v.issuedAt) fail("expiresAt");
915
+ urlValue(v.hubOrigin);
916
+ if (new URL(v.hubOrigin).origin !== v.hubOrigin) fail("hubOrigin");
917
+ parseOperation(v.operation);
918
+ if (
919
+ serviceForOperation(v.operation) !== v.service ||
920
+ (v.mode === "prepare" &&
921
+ !["calendar.connect.v1", "gmail.connect.v1"].includes(v.operation.kind))
922
+ )
923
+ fail("service operation");
924
+ return v;
925
+ }
926
+ export function parseServiceCommand(input) {
927
+ const v = object(input, "command");
928
+ exact(
929
+ v,
930
+ ["authorization", "ownerInvocation", "subscriptionDelegation"],
931
+ "command",
932
+ );
933
+ parseServiceAuthorization(v.authorization);
934
+ str(v.ownerInvocation, "ownerInvocation", 1, 65536);
935
+ if (v.subscriptionDelegation !== null)
936
+ str(v.subscriptionDelegation, "subscriptionDelegation", 1, 65536);
937
+ if (
938
+ ["calendar", "gmail"].includes(v.authorization.service) &&
939
+ v.subscriptionDelegation === null
940
+ )
941
+ fail("subscriptionDelegation");
942
+ if (v.authorization.service === "vfs" && v.subscriptionDelegation !== null)
943
+ fail("subscriptionDelegation");
944
+ return v;
945
+ }
946
+ export function parseServicePreparation(input) {
947
+ const v = object(input, "preparation");
948
+ exact(
949
+ v,
950
+ [
951
+ "version",
952
+ "accountId",
953
+ "actionId",
954
+ "revision",
955
+ "digest",
956
+ "status",
957
+ "operation",
958
+ "continuationUrl",
959
+ ],
960
+ "preparation",
961
+ );
962
+ if (
963
+ v.version !== "ixo.auth-preparation/1" ||
964
+ !["pending", "ready", "unknown"].includes(v.status)
965
+ )
966
+ fail("preparation");
967
+ tuple(v);
968
+ str(v.accountId, "accountId", 1, 100);
969
+ parseOperation(v.operation);
970
+ if (!["calendar.connect.v1", "gmail.connect.v1"].includes(v.operation.kind))
971
+ fail("preparation operation");
972
+ nullableUrl(v.continuationUrl);
973
+ if (
974
+ v.status === "ready" &&
975
+ (!v.operation.connectionId ||
976
+ !v.operation.accountLabel ||
977
+ !v.operation.scopes.length ||
978
+ v.continuationUrl !== null)
979
+ )
980
+ fail("ready preparation");
981
+ return v;
982
+ }
983
+ export function parseServiceResult(input) {
984
+ const v = object(input, "service result");
985
+ exact(
986
+ v,
987
+ [
988
+ "version",
989
+ "accountId",
990
+ "actionId",
991
+ "revision",
992
+ "digest",
993
+ "authorizationDigest",
994
+ "sequence",
995
+ "status",
996
+ "receipt",
997
+ "continuationUrl",
998
+ "accountLabel",
999
+ "resource",
1000
+ "checkedAt",
1001
+ ],
1002
+ "service result",
1003
+ );
1004
+ if (
1005
+ v.version !== "ixo.auth-service-result/1" ||
1006
+ !["pending", "succeeded", "failed", "unknown"].includes(v.status)
1007
+ )
1008
+ fail("service result");
1009
+ tuple(v);
1010
+ str(v.accountId, "accountId", 1, 100);
1011
+ pattern(v.authorizationDigest, HEX, "authorizationDigest");
1012
+ num(v.sequence, "sequence");
1013
+ num(v.checkedAt, "checkedAt");
1014
+ nullableUrl(v.continuationUrl);
1015
+ nullableString(v.accountLabel, "accountLabel");
1016
+ if (v.resource !== null) parseResourceDescriptor(v.resource);
1017
+ if (["pending", "unknown"].includes(v.status)) {
1018
+ if (v.receipt !== null) fail("receipt");
1019
+ } else {
1020
+ const r = parseReceipt(v.receipt);
1021
+ if (
1022
+ r.actionId !== v.actionId ||
1023
+ r.revision !== v.revision ||
1024
+ r.digest !== v.digest ||
1025
+ (v.status === "failed"
1026
+ ? r.kind !== "service.failure.v1"
1027
+ : r.kind === "service.failure.v1")
1028
+ )
1029
+ fail("receipt");
1030
+ }
1031
+ return v;
1032
+ }
1033
+ export function parseActionOptions(input) {
1034
+ const v = object(input, "options");
1035
+ exact(
1036
+ v,
1037
+ [
1038
+ "version",
1039
+ "accountId",
1040
+ "ownerDid",
1041
+ "bindingId",
1042
+ "bindingRevision",
1043
+ "connections",
1044
+ "targets",
1045
+ "resources",
1046
+ ],
1047
+ "options",
1048
+ );
1049
+ if (!["ixo.auth-options/1", "ixo.auth-options/2"].includes(v.version))
1050
+ fail("options.version");
1051
+ for (const k of ["accountId", "bindingId"]) str(v[k], k, 1, 100);
1052
+ str(v.ownerDid, "ownerDid");
1053
+ num(v.bindingRevision, "bindingRevision");
1054
+ for (const k of ["connections", "targets", "resources"])
1055
+ if (!Array.isArray(v[k]) || v[k].length > 100) fail(k);
1056
+ for (const c of v.connections) {
1057
+ object(c, "connection");
1058
+ exact(
1059
+ c,
1060
+ v.version === "ixo.auth-options/2"
1061
+ ? ["service", "id", "label", "scopes"]
1062
+ : ["id", "label", "scopes"],
1063
+ "connection",
1064
+ );
1065
+ if (
1066
+ v.version === "ixo.auth-options/2" &&
1067
+ !["calendar", "gmail"].includes(c.service)
1068
+ )
1069
+ fail("connection.service");
1070
+ str(c.id, "id", 1, 100);
1071
+ str(c.label, "label");
1072
+ scopeList(c.scopes);
1073
+ }
1074
+ for (const t of v.targets) {
1075
+ object(t, "target");
1076
+ exact(t, ["id", "title"], "target");
1077
+ str(t.id, "id", 1, 100);
1078
+ str(t.title, "title");
1079
+ }
1080
+ v.resources.forEach(parseResourceDescriptor);
1081
+ return v;
1082
+ }
1083
+ export const parseHubActionOptions = parseActionOptions;
1084
+ export function parseStatementProofBody(input) {
1085
+ const v = object(input, "statement proof body");
1086
+ exact(
1087
+ v,
1088
+ [
1089
+ "version",
1090
+ "accountId",
1091
+ "actionId",
1092
+ "revision",
1093
+ "digest",
1094
+ "ownerDid",
1095
+ "network",
1096
+ "audience",
1097
+ "purpose",
1098
+ "statementDigest",
1099
+ "issuedAt",
1100
+ "nonce",
1101
+ ],
1102
+ "statement proof body",
1103
+ );
1104
+ if (
1105
+ v.version !== "ixo.statement-proof/1" ||
1106
+ !SERVICE_NETWORKS.includes(v.network)
1107
+ )
1108
+ fail("statement proof body");
1109
+ tuple(v);
1110
+ str(v.accountId, "accountId", 1, 100);
1111
+ str(v.ownerDid, "ownerDid");
1112
+ str(v.audience, "audience", 1, 2000);
1113
+ str(v.purpose, "purpose", 1, 120);
1114
+ pattern(v.statementDigest, HEX, "statementDigest");
1115
+ num(v.issuedAt, "issuedAt");
1116
+ str(v.nonce, "nonce", 1, 100);
1117
+ return v;
1118
+ }
1119
+ export function parseStatementProof(input) {
1120
+ const v = object(input, "statement proof");
1121
+ exact(v, ["body", "publicKey", "signature", "statement"], "statement proof");
1122
+ parseStatementProofBody(v.body);
1123
+ pattern(v.publicKey, /^[a-f0-9]{64}$/, "publicKey");
1124
+ pattern(v.signature, /^[a-f0-9]{128}$/, "signature");
1125
+ utf8(v.statement, "statement");
1126
+ return v;
1127
+ }
1128
+
1129
+ function validCalendarInstant(value) {
1130
+ const parts =
1131
+ /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,3})?(?:Z|[+-](\d{2}):(\d{2}))$/.exec(
1132
+ value,
1133
+ );
1134
+ if (!parts) return false;
1135
+ const [, year, month, day, hour, minute, second, offsetHour, offsetMinute] =
1136
+ parts;
1137
+ const y = Number(year),
1138
+ m = Number(month),
1139
+ d = Number(day);
1140
+ const leap = y % 4 === 0 && (y % 100 !== 0 || y % 400 === 0);
1141
+ const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
1142
+ return (
1143
+ m >= 1 &&
1144
+ m <= 12 &&
1145
+ d >= 1 &&
1146
+ d <= days[m - 1] &&
1147
+ Number(hour) <= 23 &&
1148
+ Number(minute) <= 59 &&
1149
+ Number(second) <= 59 &&
1150
+ (offsetHour === undefined ||
1151
+ (Number(offsetHour) <= 23 && Number(offsetMinute) <= 59))
1152
+ );
1153
+ }
1154
+
1155
+ /** Status rules shared by review views and outcomes. */
1156
+ function receiptFitsStatus(receipt, status) {
1157
+ const bank = receipt.kind === "ixo.bank.send.v1";
1158
+ if (status === "succeeded")
1159
+ return bank
1160
+ ? receipt.code === 0 && receipt.height !== null && !("reason" in receipt)
1161
+ : receipt.kind !== "service.failure.v1";
1162
+ if (status === "failed") {
1163
+ if (receipt.kind === "service.failure.v1") return true;
1164
+ if (!bank) return false;
1165
+ if ("reason" in receipt) return true; // checked by parseReceipt
1166
+ return (
1167
+ receipt.code !== null && receipt.code !== 0 && receipt.height !== null
1168
+ );
1169
+ }
1170
+ return true;
1171
+ }
1172
+
1173
+ /**
1174
+ * Re-express a v2 outcome for a v1 caller, or return null when v1 cannot
1175
+ * represent it (expired/cancelled, or a not-included bank receipt).
1176
+ */
1177
+ export function outcomeForVersion(input, version) {
1178
+ const outcome = parseOutcome(input);
1179
+ if (version === OUTCOME_VERSION_V2)
1180
+ return { ...outcome, version: OUTCOME_VERSION_V2 };
1181
+ if (version !== OUTCOME_VERSION_V1) return fail("outcome.version");
1182
+ if (
1183
+ !V1_OUTCOME_STATUSES.includes(outcome.status) ||
1184
+ (outcome.receipt &&
1185
+ ("reason" in outcome.receipt ||
1186
+ !V1_RECEIPT_KINDS.includes(outcome.receipt.kind)))
1187
+ )
1188
+ return null;
1189
+ return parseOutcome({ ...outcome, version: OUTCOME_VERSION_V1 });
1190
+ }