@reallyme/jose 0.3.0

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/dist/facade.js ADDED
@@ -0,0 +1,433 @@
1
+ // SPDX-FileCopyrightText: Copyright © 2026 ReallyMe LLC. All rights reserved
2
+ //
3
+ // SPDX-License-Identifier: Apache-2.0
4
+ import { create, fromBinary, toBinary } from "@bufbuild/protobuf";
5
+ import { executeOperation } from "./boundary.js";
6
+ import { ReallyMeJoseError } from "./errors.js";
7
+ import { JoseErrorReason, JoseJweContentEncryptionAlgorithm, JoseJweKeyManagementAlgorithm, JoseOperationContractVersion, JoseOperationRequestSchema, JoseOperationResponseSchema, JoseSignatureAlgorithm, } from "./proto/generated/reallyme/jose/v1/jose_pb.js";
8
+ import { ensureAggregateLength, ensureBoolean, ensureBytes, ensureString, ensureUint64, invalidInput, utf8Length, } from "./validate.js";
9
+ const MAX_JWT_ACCEPTED_TYPE_VALUES = 32;
10
+ const PROTOBUF_REPEATED_STRING_OVERHEAD_BYTES = 5;
11
+ const malformedProviderResponse = () => {
12
+ throw new ReallyMeJoseError("malformed-provider-response");
13
+ };
14
+ const ownedBytes = (value) => {
15
+ ensureBytes(value);
16
+ return value.slice();
17
+ };
18
+ const optionalString = (value) => {
19
+ if (value === undefined)
20
+ return "";
21
+ ensureString(value);
22
+ return value;
23
+ };
24
+ const optionalBoolean = (value, fallback) => {
25
+ if (value === undefined)
26
+ return fallback;
27
+ ensureBoolean(value);
28
+ return value;
29
+ };
30
+ const optionalUint64 = (value) => {
31
+ if (value === undefined)
32
+ return 0n;
33
+ ensureUint64(value);
34
+ return value;
35
+ };
36
+ const validateAlgorithm = (value, allowed) => {
37
+ if (!allowed.includes(value))
38
+ invalidInput();
39
+ };
40
+ const throwJoseError = (error) => {
41
+ const branch = error.error.case;
42
+ const failWithReason = (publicBranch, reason, minimum, maximum) => {
43
+ if (reason === JoseErrorReason.UNSPECIFIED ||
44
+ JoseErrorReason[reason] === undefined ||
45
+ reason < minimum ||
46
+ reason > maximum) {
47
+ malformedProviderResponse();
48
+ }
49
+ throw new ReallyMeJoseError("jose-failure", publicBranch, reason);
50
+ };
51
+ switch (branch) {
52
+ case "primitive":
53
+ return failWithReason("primitive", error.error.value.reason, 1, 799);
54
+ case "provider":
55
+ return failWithReason("provider", error.error.value.reason, 800, 802);
56
+ case "backend":
57
+ return failWithReason("backend", error.error.value.reason, 900, 902);
58
+ default:
59
+ return malformedProviderResponse();
60
+ }
61
+ };
62
+ const decodeResponse = (responseBytes) => {
63
+ try {
64
+ return fromBinary(JoseOperationResponseSchema, responseBytes);
65
+ }
66
+ catch (_error) {
67
+ return malformedProviderResponse();
68
+ }
69
+ };
70
+ const withResponse = (request, consume) => {
71
+ const requestBytes = toBinary(JoseOperationRequestSchema, request);
72
+ let responseBytes;
73
+ try {
74
+ responseBytes = executeOperation(requestBytes);
75
+ const response = decodeResponse(responseBytes);
76
+ if (response.contractVersion !== JoseOperationContractVersion.V1) {
77
+ malformedProviderResponse();
78
+ }
79
+ if (response.response.case === undefined)
80
+ malformedProviderResponse();
81
+ if (response.response.case === "boundaryError") {
82
+ throwJoseError(response.response.value);
83
+ }
84
+ return consume(response);
85
+ }
86
+ finally {
87
+ requestBytes.fill(0);
88
+ responseBytes?.fill(0);
89
+ }
90
+ };
91
+ const compactOutcome = (outcome) => {
92
+ if (outcome.case === "error")
93
+ return throwJoseError(outcome.value);
94
+ if (outcome.case === "result") {
95
+ ensureString(outcome.value.compact);
96
+ if (outcome.value.compact.length === 0)
97
+ return malformedProviderResponse();
98
+ return outcome.value.compact;
99
+ }
100
+ return malformedProviderResponse();
101
+ };
102
+ const claimsOutcome = (outcome) => {
103
+ if (outcome.case === "error")
104
+ return throwJoseError(outcome.value);
105
+ if (outcome.case === "result")
106
+ return outcome.value.claimsJson.slice();
107
+ return malformedProviderResponse();
108
+ };
109
+ const verifyOutcome = (outcome) => {
110
+ if (outcome.case === "error")
111
+ return throwJoseError(outcome.value);
112
+ if (outcome.case !== "result")
113
+ return malformedProviderResponse();
114
+ };
115
+ const plaintextOutcome = (outcome) => {
116
+ if (outcome.case === "error")
117
+ return throwJoseError(outcome.value);
118
+ if (outcome.case === "result")
119
+ return outcome.value.plaintext.slice();
120
+ return malformedProviderResponse();
121
+ };
122
+ const jwtHeaderPolicy = (policy) => {
123
+ if (policy === undefined)
124
+ return undefined;
125
+ if (policy.acceptedTypes !== undefined &&
126
+ policy.acceptedTypes.length > MAX_JWT_ACCEPTED_TYPE_VALUES) {
127
+ invalidInput();
128
+ }
129
+ const acceptedTypes = policy.acceptedTypes === undefined ? [] : [...policy.acceptedTypes];
130
+ for (const value of acceptedTypes)
131
+ ensureString(value);
132
+ return {
133
+ allowMissingTyp: optionalBoolean(policy.allowMissingType, false),
134
+ allowEmbeddedKeyHeader: optionalBoolean(policy.allowEmbeddedKeyHeaders, false),
135
+ acceptedTypValues: acceptedTypes,
136
+ };
137
+ };
138
+ const jwtHeaderPolicyLength = (policy) => {
139
+ if (policy === undefined)
140
+ return 0;
141
+ const lengths = policy.acceptedTypValues.flatMap((value) => [utf8Length(value), PROTOBUF_REPEATED_STRING_OVERHEAD_BYTES]);
142
+ return ensureAggregateLength(...lengths);
143
+ };
144
+ const jwtTemporalPolicyLength = (policy) => {
145
+ if (policy === undefined)
146
+ return 0;
147
+ const lengths = [
148
+ utf8Length(policy.expectedAudience),
149
+ utf8Length(policy.expectedIssuer),
150
+ utf8Length(policy.expectedSubject),
151
+ ];
152
+ return ensureAggregateLength(...lengths);
153
+ };
154
+ const jwtTemporalPolicy = (policy) => {
155
+ if (policy === undefined)
156
+ return undefined;
157
+ ensureUint64(policy.verificationTimeUnixSeconds);
158
+ if (policy.verificationTimeUnixSeconds === 0n)
159
+ invalidInput();
160
+ ensureString(policy.expectedAudience);
161
+ if (policy.expectedAudience.length === 0)
162
+ invalidInput();
163
+ return {
164
+ requireExp: optionalBoolean(policy.requireExpiration, false),
165
+ requireNbf: optionalBoolean(policy.requireNotBefore, false),
166
+ requireIat: optionalBoolean(policy.requireIssuedAt, false),
167
+ clockSkewSeconds: optionalUint64(policy.clockSkewSeconds),
168
+ maxFutureIatSkewSeconds: optionalUint64(policy.maximumFutureIssuedAtSkewSeconds),
169
+ nowUnix: policy.verificationTimeUnixSeconds,
170
+ expectedAudience: policy.expectedAudience,
171
+ expectedIssuer: optionalString(policy.expectedIssuer),
172
+ expectedSubject: optionalString(policy.expectedSubject),
173
+ };
174
+ };
175
+ const jweHeaderPolicy = (policy, ownedApu, ownedApv) => {
176
+ if (policy === undefined)
177
+ return undefined;
178
+ return {
179
+ requireKid: optionalBoolean(policy.requireKeyIdentifier, false),
180
+ expectedKid: policy.expectedKeyIdentifier === undefined
181
+ ? undefined
182
+ : { value: optionalString(policy.expectedKeyIdentifier) },
183
+ expectedTyp: policy.expectedType === undefined
184
+ ? undefined
185
+ : { value: optionalString(policy.expectedType) },
186
+ expectedCty: policy.expectedContentType === undefined
187
+ ? undefined
188
+ : { value: optionalString(policy.expectedContentType) },
189
+ expectedApu: ownedApu === undefined ? undefined : { value: ownedApu },
190
+ expectedApv: ownedApv === undefined ? undefined : { value: ownedApv },
191
+ };
192
+ };
193
+ export const ReallyMeJose = Object.freeze({
194
+ signJws(options) {
195
+ validateAlgorithm(options.algorithm, [JoseSignatureAlgorithm.EDDSA, JoseSignatureAlgorithm.ES256]);
196
+ const privateKey = ownedBytes(options.privateKey);
197
+ const payload = ownedBytes(options.payload);
198
+ try {
199
+ ensureAggregateLength(privateKey.length, payload.length);
200
+ const request = create(JoseOperationRequestSchema, {
201
+ operation: { case: "jwsSign", value: { algorithm: options.algorithm, privateKey, payload } },
202
+ });
203
+ return withResponse(request, (response) => {
204
+ const operation = response.response;
205
+ if (operation.case === "jwsSign")
206
+ return compactOutcome(operation.value.outcome);
207
+ return malformedProviderResponse();
208
+ });
209
+ }
210
+ finally {
211
+ privateKey.fill(0);
212
+ payload.fill(0);
213
+ }
214
+ },
215
+ verifyJws(options) {
216
+ validateAlgorithm(options.algorithm, [JoseSignatureAlgorithm.EDDSA, JoseSignatureAlgorithm.ES256]);
217
+ ensureString(options.compact);
218
+ const publicKey = ownedBytes(options.publicKey);
219
+ try {
220
+ ensureAggregateLength(utf8Length(options.compact), publicKey.length);
221
+ const request = create(JoseOperationRequestSchema, {
222
+ operation: {
223
+ case: "jwsVerify",
224
+ value: { algorithm: options.algorithm, compact: options.compact, publicKey },
225
+ },
226
+ });
227
+ withResponse(request, (response) => {
228
+ const operation = response.response;
229
+ if (operation.case === "jwsVerify")
230
+ return verifyOutcome(operation.value.outcome);
231
+ return malformedProviderResponse();
232
+ });
233
+ }
234
+ finally {
235
+ publicKey.fill(0);
236
+ }
237
+ },
238
+ encodeUnsignedJwt(claimsJson) {
239
+ const claims = ownedBytes(claimsJson);
240
+ try {
241
+ ensureAggregateLength(claims.length);
242
+ const request = create(JoseOperationRequestSchema, {
243
+ operation: { case: "jwtEncodeUnsigned", value: { claimsJson: claims } },
244
+ });
245
+ return withResponse(request, (response) => {
246
+ const operation = response.response;
247
+ if (operation.case === "jwtEncodeUnsigned") {
248
+ return compactOutcome(operation.value.outcome);
249
+ }
250
+ return malformedProviderResponse();
251
+ });
252
+ }
253
+ finally {
254
+ claims.fill(0);
255
+ }
256
+ },
257
+ decodeUnsignedJwt(compact) {
258
+ ensureString(compact);
259
+ ensureAggregateLength(utf8Length(compact));
260
+ const request = create(JoseOperationRequestSchema, {
261
+ operation: { case: "jwtDecodeUnsigned", value: { compact } },
262
+ });
263
+ return withResponse(request, (response) => {
264
+ const operation = response.response;
265
+ if (operation.case === "jwtDecodeUnsigned")
266
+ return claimsOutcome(operation.value.outcome);
267
+ return malformedProviderResponse();
268
+ });
269
+ },
270
+ signJwt(options) {
271
+ const claims = ownedBytes(options.claimsJson);
272
+ const jwk = ownedBytes(options.jwkJson);
273
+ const privateKey = ownedBytes(options.privateKey);
274
+ const type = optionalString(options.type);
275
+ try {
276
+ ensureAggregateLength(claims.length, jwk.length, privateKey.length, utf8Length(type));
277
+ const request = create(JoseOperationRequestSchema, {
278
+ operation: {
279
+ case: "jwtSign",
280
+ value: { claimsJson: claims, jwkJson: jwk, privateKey, typ: type },
281
+ },
282
+ });
283
+ return withResponse(request, (response) => {
284
+ const operation = response.response;
285
+ if (operation.case === "jwtSign")
286
+ return compactOutcome(operation.value.outcome);
287
+ return malformedProviderResponse();
288
+ });
289
+ }
290
+ finally {
291
+ claims.fill(0);
292
+ jwk.fill(0);
293
+ privateKey.fill(0);
294
+ }
295
+ },
296
+ verifyJwt(options) {
297
+ ensureString(options.compact);
298
+ const jwk = ownedBytes(options.jwkJson);
299
+ const publicKey = ownedBytes(options.publicKey);
300
+ try {
301
+ const headerPolicy = jwtHeaderPolicy(options.headerPolicy);
302
+ const temporalPolicy = jwtTemporalPolicy(options.temporalPolicy);
303
+ ensureAggregateLength(utf8Length(options.compact), jwk.length, publicKey.length, jwtHeaderPolicyLength(headerPolicy), jwtTemporalPolicyLength(temporalPolicy));
304
+ const request = create(JoseOperationRequestSchema, {
305
+ operation: {
306
+ case: "jwtVerify",
307
+ value: {
308
+ compact: options.compact,
309
+ jwkJson: jwk,
310
+ publicKey,
311
+ headerPolicy,
312
+ temporalPolicy,
313
+ signatureOnly: optionalBoolean(options.signatureOnly, false),
314
+ },
315
+ },
316
+ });
317
+ return withResponse(request, (response) => {
318
+ const operation = response.response;
319
+ if (operation.case === "jwtVerify")
320
+ return claimsOutcome(operation.value.outcome);
321
+ return malformedProviderResponse();
322
+ });
323
+ }
324
+ finally {
325
+ jwk.fill(0);
326
+ publicKey.fill(0);
327
+ }
328
+ },
329
+ encryptJwe(options) {
330
+ validateAlgorithm(options.keyManagementAlgorithm, [
331
+ JoseJweKeyManagementAlgorithm.DIRECT,
332
+ JoseJweKeyManagementAlgorithm.ECDH_ES_P256,
333
+ JoseJweKeyManagementAlgorithm.ECDH_ES_P384,
334
+ JoseJweKeyManagementAlgorithm.ECDH_ES_P521,
335
+ ]);
336
+ validateAlgorithm(options.contentEncryptionAlgorithm, [
337
+ JoseJweContentEncryptionAlgorithm.A128GCM,
338
+ JoseJweContentEncryptionAlgorithm.A192GCM,
339
+ JoseJweContentEncryptionAlgorithm.A256GCM,
340
+ ]);
341
+ const key = ownedBytes(options.key);
342
+ const plaintext = ownedBytes(options.plaintext);
343
+ const apu = ownedBytes(options.agreementPartyUInfo ?? new Uint8Array());
344
+ const apv = ownedBytes(options.agreementPartyVInfo ?? new Uint8Array());
345
+ const keyIdentifier = optionalString(options.keyIdentifier);
346
+ const type = optionalString(options.type);
347
+ const contentType = optionalString(options.contentType);
348
+ try {
349
+ ensureAggregateLength(key.length, plaintext.length, apu.length, apv.length, utf8Length(keyIdentifier), utf8Length(type), utf8Length(contentType));
350
+ const request = create(JoseOperationRequestSchema, {
351
+ operation: {
352
+ case: "jweEncrypt",
353
+ value: {
354
+ keyManagementAlgorithm: options.keyManagementAlgorithm,
355
+ contentEncryptionAlgorithm: options.contentEncryptionAlgorithm,
356
+ key,
357
+ plaintext,
358
+ kid: keyIdentifier,
359
+ apu,
360
+ apv,
361
+ typ: type,
362
+ cty: contentType,
363
+ },
364
+ },
365
+ });
366
+ return withResponse(request, (response) => {
367
+ const operation = response.response;
368
+ if (operation.case === "jweEncrypt")
369
+ return compactOutcome(operation.value.outcome);
370
+ return malformedProviderResponse();
371
+ });
372
+ }
373
+ finally {
374
+ key.fill(0);
375
+ plaintext.fill(0);
376
+ apu.fill(0);
377
+ apv.fill(0);
378
+ }
379
+ },
380
+ decryptJwe(options) {
381
+ ensureString(options.compact);
382
+ validateAlgorithm(options.keyManagementAlgorithm, [
383
+ JoseJweKeyManagementAlgorithm.DIRECT,
384
+ JoseJweKeyManagementAlgorithm.ECDH_ES_P256,
385
+ JoseJweKeyManagementAlgorithm.ECDH_ES_P384,
386
+ JoseJweKeyManagementAlgorithm.ECDH_ES_P521,
387
+ ]);
388
+ validateAlgorithm(options.contentEncryptionAlgorithm, [
389
+ JoseJweContentEncryptionAlgorithm.A128GCM,
390
+ JoseJweContentEncryptionAlgorithm.A192GCM,
391
+ JoseJweContentEncryptionAlgorithm.A256GCM,
392
+ ]);
393
+ const key = ownedBytes(options.key);
394
+ const expectedApu = options.headerPolicy?.expectedAgreementPartyUInfo === undefined
395
+ ? undefined
396
+ : ownedBytes(options.headerPolicy.expectedAgreementPartyUInfo);
397
+ const expectedApv = options.headerPolicy?.expectedAgreementPartyVInfo === undefined
398
+ ? undefined
399
+ : ownedBytes(options.headerPolicy.expectedAgreementPartyVInfo);
400
+ try {
401
+ ensureAggregateLength(utf8Length(options.compact), key.length, expectedApu?.length ?? 0, expectedApv?.length ?? 0, options.headerPolicy?.expectedKeyIdentifier === undefined
402
+ ? 0
403
+ : utf8Length(options.headerPolicy.expectedKeyIdentifier), options.headerPolicy?.expectedType === undefined
404
+ ? 0
405
+ : utf8Length(options.headerPolicy.expectedType), options.headerPolicy?.expectedContentType === undefined
406
+ ? 0
407
+ : utf8Length(options.headerPolicy.expectedContentType));
408
+ const request = create(JoseOperationRequestSchema, {
409
+ operation: {
410
+ case: "jweDecrypt",
411
+ value: {
412
+ compact: options.compact,
413
+ keyManagementAlgorithm: options.keyManagementAlgorithm,
414
+ contentEncryptionAlgorithm: options.contentEncryptionAlgorithm,
415
+ key,
416
+ headerPolicy: jweHeaderPolicy(options.headerPolicy, expectedApu, expectedApv),
417
+ },
418
+ },
419
+ });
420
+ return withResponse(request, (response) => {
421
+ const operation = response.response;
422
+ if (operation.case === "jweDecrypt")
423
+ return plaintextOutcome(operation.value.outcome);
424
+ return malformedProviderResponse();
425
+ });
426
+ }
427
+ finally {
428
+ key.fill(0);
429
+ expectedApu?.fill(0);
430
+ expectedApv?.fill(0);
431
+ }
432
+ },
433
+ });
@@ -0,0 +1,9 @@
1
+ export { executeOperation, executeOperationJson } from "./boundary.js";
2
+ export { ReallyMeJoseError } from "./errors.js";
3
+ export type { ReallyMeJoseErrorBranch, ReallyMeJoseSdkErrorCode, } from "./errors.js";
4
+ export { ReallyMeJose } from "./facade.js";
5
+ export type { ReallyMeJoseDecryptJweOptions, ReallyMeJoseEncryptJweOptions, ReallyMeJoseJweHeaderPolicy, ReallyMeJoseJwtHeaderPolicy, ReallyMeJoseJwtTemporalPolicy, ReallyMeJoseSignJwsOptions, ReallyMeJoseSignJwtOptions, ReallyMeJoseVerifyJwsOptions, ReallyMeJoseVerifyJwtOptions, } from "./facade.js";
6
+ export { bestEffortClear } from "./memory.js";
7
+ export { createReallyMeJoseWasmProvider, installReallyMeJoseWasmProvider, } from "./provider.js";
8
+ export type { ReallyMeJoseWasmProvider } from "./provider.js";
9
+ export { JoseErrorReason, JoseJweContentEncryptionAlgorithm, JoseJweKeyManagementAlgorithm, JoseSignatureAlgorithm, } from "./proto/generated/reallyme/jose/v1/jose_pb.js";
package/dist/index.js ADDED
@@ -0,0 +1,9 @@
1
+ // SPDX-FileCopyrightText: Copyright © 2026 ReallyMe LLC. All rights reserved
2
+ //
3
+ // SPDX-License-Identifier: Apache-2.0
4
+ export { executeOperation, executeOperationJson } from "./boundary.js";
5
+ export { ReallyMeJoseError } from "./errors.js";
6
+ export { ReallyMeJose } from "./facade.js";
7
+ export { bestEffortClear } from "./memory.js";
8
+ export { createReallyMeJoseWasmProvider, installReallyMeJoseWasmProvider, } from "./provider.js";
9
+ export { JoseErrorReason, JoseJweContentEncryptionAlgorithm, JoseJweKeyManagementAlgorithm, JoseSignatureAlgorithm, } from "./proto/generated/reallyme/jose/v1/jose_pb.js";
@@ -0,0 +1,2 @@
1
+ /** Best-effort cleanup for caller-controlled mutable byte storage. */
2
+ export declare const bestEffortClear: (value: Uint8Array) => void;
package/dist/memory.js ADDED
@@ -0,0 +1,10 @@
1
+ // SPDX-FileCopyrightText: Copyright © 2026 ReallyMe LLC. All rights reserved
2
+ //
3
+ // SPDX-License-Identifier: Apache-2.0
4
+ import { invalidInput } from "./validate.js";
5
+ /** Best-effort cleanup for caller-controlled mutable byte storage. */
6
+ export const bestEffortClear = (value) => {
7
+ if (!(value instanceof Uint8Array))
8
+ return invalidInput();
9
+ value.fill(0);
10
+ };