@lepistabioinformatics/mycelium-sdk 2.0.0 → 2.1.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/index.d.ts CHANGED
@@ -1,6 +1,8 @@
1
- import { P as Profile } from './profile-CUKBifyR.js';
2
- export { A as AccountMetaKey, a as AccountMetaKeySchema, L as LicensedResource, b as LicensedResourceSchema, c as LicensedResources, d as LicensedResourcesSchema, e as Permission, f as PermissionSchema, g as ProfileData, h as ProfileMeta, i as ProfileMetaSchema, j as ProfileSchema, R as RelatedAccounts, l as licensedResourceFromUrlString, p as permissionFromInt, k as permissionToInt, t as toLicensesVector } from './profile-CUKBifyR.js';
1
+ import { P as Profile, a as ProfileJwksFetcher, J as JwksProfileSignatureVerifier } from './profileSignatureEnforcement-C-bhVkEp.js';
2
+ export { A as AccountMetaKey, b as AccountMetaKeySchema, C as CachedProfileKeys, F as FetchedProfileJwks, L as LicensedResource, c as LicensedResourceSchema, d as LicensedResources, e as LicensedResourcesSchema, M as MonotonicClock, f as Permission, g as PermissionSchema, h as ProfileData, i as ProfileJwksFetchError, j as ProfileKeyStore, k as ProfileMeta, l as ProfileMetaSchema, m as ProfileSchema, R as RelatedAccounts, n as SIGNATURE_INTERNAL_DETAIL, o as SIGNATURE_REJECTION_DETAIL, S as SignatureRejectionListener, p as SignatureVerificationOutcome, q as fetchProfileJwks, r as licensedResourceFromUrlString, s as permissionFromInt, t as permissionToInt, u as toLicensesVector, v as verifyRequestProfile } from './profileSignatureEnforcement-C-bhVkEp.js';
3
3
  import { z } from 'zod';
4
+ import { KeyObject } from 'node:crypto';
5
+ import 'node:http';
4
6
 
5
7
  declare class MyceliumError extends Error {
6
8
  code?: string;
@@ -17,6 +19,26 @@ declare class InsufficientLicensesError extends MyceliumError {
17
19
  declare class ProfileDecodingError extends MyceliumError {
18
20
  constructor(message: string);
19
21
  }
22
+ declare const PROFILE_SIGNATURE_INVALID_CODE = "MYC_PROFILE_SIGNATURE_INVALID";
23
+ declare const PROFILE_SIGNATURE_CONFIG_INVALID_CODE = "MYC_PROFILE_SIGNATURE_CONFIG_INVALID";
24
+ type ProfileSignatureRejectionReason = "missing_profile" | "missing_signature" | "duplicate_header" | "malformed_signature" | "unsupported_algorithm" | "unknown_key" | "invalid_signature" | "invalid_claims" | "timestamp_out_of_tolerance" | "profile_hash_mismatch" | "audience_mismatch" | "invalid_profile";
25
+ /**
26
+ * Invalid verification configuration (`MYCELIUM_JWKS_URL` and related
27
+ * variables) or an unsafe/malformed gateway JWKS. A malformed setting must
28
+ * stop the service instead of silently disabling verification. Messages
29
+ * name variables, never values.
30
+ */
31
+ declare class ProfileSignatureConfigurationError extends MyceliumError {
32
+ constructor(message: string);
33
+ }
34
+ /**
35
+ * Signature rejected. `reason` is stable and log-safe; HTTP integrations
36
+ * answer with a generic message and never expose it to clients.
37
+ */
38
+ declare class ProfileSignatureError extends MyceliumError {
39
+ readonly reason: ProfileSignatureRejectionReason;
40
+ constructor(reason: ProfileSignatureRejectionReason);
41
+ }
20
42
 
21
43
  declare const DEFAULT_PROFILE_KEY = "x-mycelium-profile";
22
44
  declare const DEFAULT_EMAIL_KEY = "x-mycelium-email";
@@ -25,6 +47,30 @@ declare const DEFAULT_MYCELIUM_ROLE_KEY = "x-mycelium-role";
25
47
  declare const DEFAULT_REQUEST_ID_KEY = "x-mycelium-request-id";
26
48
  declare const DEFAULT_CONNECTION_STRING_KEY = "x-mycelium-connection-string";
27
49
  declare const DEFAULT_TENANT_ID_KEY = "x-mycelium-tenant-id";
50
+ declare const DEFAULT_PROFILE_SIGNATURE_KEY = "x-mycelium-profile-signature";
51
+ /** URL of the gateway profile JWKS; its presence enables verification. */
52
+ declare const PROFILE_JWKS_URL_ENV = "MYCELIUM_JWKS_URL";
53
+ /** Development-only switch accepting an `http://` JWKS URL ("true"/"false"). */
54
+ declare const PROFILE_JWKS_ALLOW_INSECURE_HTTP_ENV = "MYCELIUM_JWKS_ALLOW_INSECURE_HTTP";
55
+ /** Path where the gateway publishes the profile JWKS. */
56
+ declare const PROFILE_JWKS_PATH = "/.well-known/mycelium-profile-jwks.json";
57
+ declare const PROFILE_JWKS_FETCH_TIMEOUT_SECONDS = 5;
58
+ declare const PROFILE_JWKS_MAX_BYTES: number;
59
+ /** Minimum interval between JWKS requests (unknown `kid`, failed refresh). */
60
+ declare const PROFILE_JWKS_REFETCH_COOLDOWN_SECONDS = 30;
61
+ /** Shorter retry interval while no key set was ever downloaded (first use). */
62
+ declare const PROFILE_JWKS_EMPTY_RETRY_SECONDS = 5;
63
+ declare const PROFILE_JWKS_DEFAULT_MAX_AGE_SECONDS = 43200;
64
+ declare const PROFILE_JWKS_MIN_MAX_AGE_SECONDS = 60;
65
+ declare const PROFILE_JWKS_MAX_MAX_AGE_SECONDS = 86400;
66
+ /** How long an expired key set stays trusted while refreshes fail. */
67
+ declare const PROFILE_JWKS_MAX_STALE_SECONDS = 86400;
68
+ declare const PROFILE_SIGNATURE_TOLERANCE_ENV = "MYC_PROFILE_SIGNATURE_TOLERANCE_SECONDS";
69
+ declare const PROFILE_SIGNATURE_AUDIENCE_ENV = "MYC_PROFILE_SIGNATURE_AUDIENCE";
70
+ declare const DEFAULT_PROFILE_SIGNATURE_TOLERANCE_SECONDS = 60;
71
+ /** Largest accepted tolerance: it is the replay window of a signature. */
72
+ declare const MAX_PROFILE_SIGNATURE_TOLERANCE_SECONDS = 300;
73
+ declare const MAX_PROFILE_SIGNATURE_BYTES = 4096;
28
74
 
29
75
  declare const VerboseStatusSchema: z.ZodEnum<["unverified", "verified", "inactive", "archived", "deleted", "unknown"]>;
30
76
  type VerboseStatus = z.infer<typeof VerboseStatusSchema>;
@@ -135,4 +181,104 @@ type SafeDecodeResult = {
135
181
  declare function safeDecodeAndDecompressProfileFromBase64(input: string | Buffer, opts?: DecodeOptions): SafeDecodeResult;
136
182
  declare function compressAndEncodeProfileToBase64(profile: Profile): string;
137
183
 
138
- export { DEFAULT_CONNECTION_STRING_KEY, DEFAULT_EMAIL_KEY, DEFAULT_MYCELIUM_ROLE_KEY, DEFAULT_PROFILE_KEY, DEFAULT_REQUEST_ID_KEY, DEFAULT_SCOPE_KEY, DEFAULT_TENANT_ID_KEY, type DecodeOptions, InsufficientLicensesError, InsufficientPrivilegesError, MyceliumError, type Owner, OwnerSchema, Profile, ProfileDecodingError, type SafeDecodeResult, type TenantOwnership, TenantOwnershipSchema, type TenantsOwnership, TenantsOwnershipSchema, type VerboseStatus, VerboseStatusSchema, compressAndEncodeProfileToBase64, decodeAndDecompressProfileFromBase64, safeDecodeAndDecompressProfileFromBase64, tenantOwnershipFromUrlString, toOwnershipVector };
184
+ /**
185
+ * One verification pass: the trusted Ed25519 keys at an instant, by `kid`,
186
+ * and the rules. Immutable; the key map is private.
187
+ *
188
+ * The JWKS-backed verifier builds one per request from its cached keys; the
189
+ * contract tests build one directly. The audience is optional here so the
190
+ * shared vectors can exercise both cases; a configured service always has
191
+ * one (see `JwksProfileSignatureVerifier`).
192
+ */
193
+ declare class ProfileSignatureVerifier {
194
+ #private;
195
+ readonly toleranceSeconds: number;
196
+ readonly expectedAudience: string | undefined;
197
+ constructor(keys: ReadonlyMap<string, KeyObject>, toleranceSeconds: number, expectedAudience?: string);
198
+ keyFor(kid: string): KeyObject | undefined;
199
+ get keyVersions(): string[];
200
+ }
201
+ /** Canonical decimal key version (`kid`): 1..4294967295, no leading zeros. */
202
+ declare function isCanonicalKeyVersion(raw: string): boolean;
203
+
204
+ /** Unpadded Base64URL SHA-256 of the exact profile header value. */
205
+ declare function profileHeaderHash(profileHeader: string): string;
206
+ /**
207
+ * Verify that `signatureHeader` authenticates `profileHeader`.
208
+ *
209
+ * Rejects with `ProfileSignatureError` (stable `reason`) on any failure, and
210
+ * with `RangeError` for an invalid verifier clock (internal error). Does not
211
+ * decode the profile; see `verifyAndDecodeProfile`.
212
+ */
213
+ declare function verifyProfileSignature(profileHeader: string, signatureHeader: string, verifier: ProfileSignatureVerifier, nowSeconds?: number): Promise<void>;
214
+ /** Verify the signature, then decode the profile (`invalid_profile`). */
215
+ declare function verifyAndDecodeProfile(profileHeader: string, signatureHeader: string, verifier: ProfileSignatureVerifier, nowSeconds?: number): Promise<Profile>;
216
+
217
+ type EnvironmentSource = Readonly<Record<string, string | undefined>>;
218
+ /**
219
+ * Build the verifier from an environment snapshot (default `process.env`).
220
+ *
221
+ * Returns `undefined` when `MYCELIUM_JWKS_URL` is absent (verification
222
+ * disabled, legacy behavior). With the URL set, `MYC_PROFILE_SIGNATURE_AUDIENCE`
223
+ * is required. Every present setting is validated even when disabled; an
224
+ * invalid one throws `ProfileSignatureConfigurationError`, never "disabled".
225
+ *
226
+ * Synchronous and network-free: the keys are fetched on first use. Prefer
227
+ * `prepareProfileSignatureVerifier()` at startup to download them before
228
+ * serving.
229
+ */
230
+ declare function loadProfileSignatureVerifierFromEnv(env?: EnvironmentSource, fetcher?: ProfileJwksFetcher): JwksProfileSignatureVerifier | undefined;
231
+ /**
232
+ * Opt-in: read the settings and download the gateway JWKS before serving.
233
+ *
234
+ * Rejects on invalid settings or when the keys cannot be fetched. Without
235
+ * it, the Express and Fastify integrations download the keys on the first
236
+ * signed request, so the service does not depend on the gateway to start.
237
+ * Resolves `undefined` when verification is disabled.
238
+ */
239
+ declare function prepareProfileSignatureVerifier(env?: EnvironmentSource, fetcher?: ProfileJwksFetcher): Promise<JwksProfileSignatureVerifier | undefined>;
240
+
241
+ /**
242
+ * Parse the gateway profile JWKS (`{"keys": [...]}`) into keys by `kid`.
243
+ *
244
+ * Strict and all-or-nothing: one unsafe entry (private member `d`, other key
245
+ * type or curve, wrong length, non-canonical or duplicated `kid`, `use` other
246
+ * than `sig`, `alg` other than `EdDSA`) refuses the whole document, so the
247
+ * verifier keeps its last valid set. Unknown members are ignored (RFC 7517).
248
+ * Throws `ProfileSignatureConfigurationError`.
249
+ */
250
+ declare function parseProfileJwks(document: string): Map<string, KeyObject>;
251
+
252
+ /**
253
+ * Validate where the gateway profile JWKS is fetched from.
254
+ *
255
+ * The location comes only from the service configuration, never from a
256
+ * request: following a URL found in the message being verified would let an
257
+ * attacker choose the keys. `https:` is required; `http:` only with the
258
+ * explicit development switch (a warning is logged).
259
+ *
260
+ * Two forms are accepted: the complete endpoint, ending in
261
+ * `PROFILE_JWKS_PATH`, used as is; or the gateway base
262
+ * (`mycelium.example.com`, `https://host/prefix`), to which
263
+ * `PROFILE_JWKS_PATH` is appended. Without a scheme, `https://` is assumed.
264
+ */
265
+ declare function parseProfileJwksUrl(raw: string, allowInsecureHttp: boolean): URL;
266
+
267
+ /**
268
+ * How long a fetched profile JWKS may be cached, in seconds.
269
+ *
270
+ * Reads the `max-age` directive of a `Cache-Control` value and clamps it to
271
+ * 60..86400; 43200 (12 h) when the header or directive is absent or
272
+ * unreadable. Same rule as the gateway and every SDK (`jwks-vectors.json`).
273
+ */
274
+ declare function readJwksCacheMaxAge(cacheControl: string | null | undefined): number;
275
+
276
+ /**
277
+ * The canonical key version named by a signature's protected header.
278
+ *
279
+ * Used only to decide whether an `unknown_key` rejection deserves a JWKS
280
+ * refetch: a missing or non-canonical `kid` never triggers network work.
281
+ */
282
+ declare function readSignatureKeyVersion(signatureHeader: string): string | undefined;
283
+
284
+ export { DEFAULT_CONNECTION_STRING_KEY, DEFAULT_EMAIL_KEY, DEFAULT_MYCELIUM_ROLE_KEY, DEFAULT_PROFILE_KEY, DEFAULT_PROFILE_SIGNATURE_KEY, DEFAULT_PROFILE_SIGNATURE_TOLERANCE_SECONDS, DEFAULT_REQUEST_ID_KEY, DEFAULT_SCOPE_KEY, DEFAULT_TENANT_ID_KEY, type DecodeOptions, type EnvironmentSource, InsufficientLicensesError, InsufficientPrivilegesError, JwksProfileSignatureVerifier, MAX_PROFILE_SIGNATURE_BYTES, MAX_PROFILE_SIGNATURE_TOLERANCE_SECONDS, MyceliumError, type Owner, OwnerSchema, PROFILE_JWKS_ALLOW_INSECURE_HTTP_ENV, PROFILE_JWKS_DEFAULT_MAX_AGE_SECONDS, PROFILE_JWKS_EMPTY_RETRY_SECONDS, PROFILE_JWKS_FETCH_TIMEOUT_SECONDS, PROFILE_JWKS_MAX_BYTES, PROFILE_JWKS_MAX_MAX_AGE_SECONDS, PROFILE_JWKS_MAX_STALE_SECONDS, PROFILE_JWKS_MIN_MAX_AGE_SECONDS, PROFILE_JWKS_PATH, PROFILE_JWKS_REFETCH_COOLDOWN_SECONDS, PROFILE_JWKS_URL_ENV, PROFILE_SIGNATURE_AUDIENCE_ENV, PROFILE_SIGNATURE_CONFIG_INVALID_CODE, PROFILE_SIGNATURE_INVALID_CODE, PROFILE_SIGNATURE_TOLERANCE_ENV, Profile, ProfileDecodingError, ProfileJwksFetcher, ProfileSignatureConfigurationError, ProfileSignatureError, type ProfileSignatureRejectionReason, ProfileSignatureVerifier, type SafeDecodeResult, type TenantOwnership, TenantOwnershipSchema, type TenantsOwnership, TenantsOwnershipSchema, type VerboseStatus, VerboseStatusSchema, compressAndEncodeProfileToBase64, decodeAndDecompressProfileFromBase64, isCanonicalKeyVersion, loadProfileSignatureVerifierFromEnv, parseProfileJwks, parseProfileJwksUrl, prepareProfileSignatureVerifier, profileHeaderHash, readJwksCacheMaxAge, readSignatureKeyVersion, safeDecodeAndDecompressProfileFromBase64, tenantOwnershipFromUrlString, toOwnershipVector, verifyAndDecodeProfile, verifyProfileSignature };
package/dist/index.js CHANGED
@@ -4,66 +4,144 @@ import {
4
4
  DEFAULT_EMAIL_KEY,
5
5
  DEFAULT_MYCELIUM_ROLE_KEY,
6
6
  DEFAULT_PROFILE_KEY,
7
+ DEFAULT_PROFILE_SIGNATURE_KEY,
8
+ DEFAULT_PROFILE_SIGNATURE_TOLERANCE_SECONDS,
7
9
  DEFAULT_REQUEST_ID_KEY,
8
10
  DEFAULT_SCOPE_KEY,
9
11
  DEFAULT_TENANT_ID_KEY,
10
12
  InsufficientLicensesError,
11
13
  InsufficientPrivilegesError,
14
+ JwksProfileSignatureVerifier,
12
15
  LicensedResourceSchema,
13
16
  LicensedResourcesSchema,
17
+ MAX_PROFILE_SIGNATURE_BYTES,
18
+ MAX_PROFILE_SIGNATURE_TOLERANCE_SECONDS,
14
19
  MyceliumError,
15
20
  OwnerSchema,
21
+ PROFILE_JWKS_ALLOW_INSECURE_HTTP_ENV,
22
+ PROFILE_JWKS_DEFAULT_MAX_AGE_SECONDS,
23
+ PROFILE_JWKS_EMPTY_RETRY_SECONDS,
24
+ PROFILE_JWKS_FETCH_TIMEOUT_SECONDS,
25
+ PROFILE_JWKS_MAX_BYTES,
26
+ PROFILE_JWKS_MAX_MAX_AGE_SECONDS,
27
+ PROFILE_JWKS_MAX_STALE_SECONDS,
28
+ PROFILE_JWKS_MIN_MAX_AGE_SECONDS,
29
+ PROFILE_JWKS_PATH,
30
+ PROFILE_JWKS_REFETCH_COOLDOWN_SECONDS,
31
+ PROFILE_JWKS_URL_ENV,
32
+ PROFILE_SIGNATURE_AUDIENCE_ENV,
33
+ PROFILE_SIGNATURE_CONFIG_INVALID_CODE,
34
+ PROFILE_SIGNATURE_INVALID_CODE,
35
+ PROFILE_SIGNATURE_TOLERANCE_ENV,
16
36
  Permission,
17
37
  PermissionSchema,
18
38
  Profile,
19
39
  ProfileDecodingError,
40
+ ProfileJwksFetchError,
41
+ ProfileKeyStore,
20
42
  ProfileMetaSchema,
21
43
  ProfileSchema,
44
+ ProfileSignatureConfigurationError,
45
+ ProfileSignatureError,
46
+ ProfileSignatureVerifier,
47
+ SIGNATURE_INTERNAL_DETAIL,
48
+ SIGNATURE_REJECTION_DETAIL,
22
49
  TenantOwnershipSchema,
23
50
  TenantsOwnershipSchema,
24
51
  VerboseStatusSchema,
25
52
  compressAndEncodeProfileToBase64,
26
53
  decodeAndDecompressProfileFromBase64,
54
+ fetchProfileJwks,
55
+ isCanonicalKeyVersion,
27
56
  licensedResourceFromUrlString,
57
+ loadProfileSignatureVerifierFromEnv,
58
+ parseProfileJwks,
59
+ parseProfileJwksUrl,
28
60
  permissionFromInt,
29
61
  permissionToInt,
62
+ prepareProfileSignatureVerifier,
63
+ profileHeaderHash,
64
+ readJwksCacheMaxAge,
65
+ readSignatureKeyVersion,
30
66
  safeDecodeAndDecompressProfileFromBase64,
31
67
  tenantOwnershipFromUrlString,
32
68
  toLicensesVector,
33
- toOwnershipVector
34
- } from "./chunk-VPKHPMDS.js";
69
+ toOwnershipVector,
70
+ verifyAndDecodeProfile,
71
+ verifyProfileSignature,
72
+ verifyRequestProfile
73
+ } from "./chunk-FQWYV2WC.js";
35
74
  export {
36
75
  AccountMetaKeySchema,
37
76
  DEFAULT_CONNECTION_STRING_KEY,
38
77
  DEFAULT_EMAIL_KEY,
39
78
  DEFAULT_MYCELIUM_ROLE_KEY,
40
79
  DEFAULT_PROFILE_KEY,
80
+ DEFAULT_PROFILE_SIGNATURE_KEY,
81
+ DEFAULT_PROFILE_SIGNATURE_TOLERANCE_SECONDS,
41
82
  DEFAULT_REQUEST_ID_KEY,
42
83
  DEFAULT_SCOPE_KEY,
43
84
  DEFAULT_TENANT_ID_KEY,
44
85
  InsufficientLicensesError,
45
86
  InsufficientPrivilegesError,
87
+ JwksProfileSignatureVerifier,
46
88
  LicensedResourceSchema,
47
89
  LicensedResourcesSchema,
90
+ MAX_PROFILE_SIGNATURE_BYTES,
91
+ MAX_PROFILE_SIGNATURE_TOLERANCE_SECONDS,
48
92
  MyceliumError,
49
93
  OwnerSchema,
94
+ PROFILE_JWKS_ALLOW_INSECURE_HTTP_ENV,
95
+ PROFILE_JWKS_DEFAULT_MAX_AGE_SECONDS,
96
+ PROFILE_JWKS_EMPTY_RETRY_SECONDS,
97
+ PROFILE_JWKS_FETCH_TIMEOUT_SECONDS,
98
+ PROFILE_JWKS_MAX_BYTES,
99
+ PROFILE_JWKS_MAX_MAX_AGE_SECONDS,
100
+ PROFILE_JWKS_MAX_STALE_SECONDS,
101
+ PROFILE_JWKS_MIN_MAX_AGE_SECONDS,
102
+ PROFILE_JWKS_PATH,
103
+ PROFILE_JWKS_REFETCH_COOLDOWN_SECONDS,
104
+ PROFILE_JWKS_URL_ENV,
105
+ PROFILE_SIGNATURE_AUDIENCE_ENV,
106
+ PROFILE_SIGNATURE_CONFIG_INVALID_CODE,
107
+ PROFILE_SIGNATURE_INVALID_CODE,
108
+ PROFILE_SIGNATURE_TOLERANCE_ENV,
50
109
  Permission,
51
110
  PermissionSchema,
52
111
  Profile,
53
112
  ProfileDecodingError,
113
+ ProfileJwksFetchError,
114
+ ProfileKeyStore,
54
115
  ProfileMetaSchema,
55
116
  ProfileSchema,
117
+ ProfileSignatureConfigurationError,
118
+ ProfileSignatureError,
119
+ ProfileSignatureVerifier,
120
+ SIGNATURE_INTERNAL_DETAIL,
121
+ SIGNATURE_REJECTION_DETAIL,
56
122
  TenantOwnershipSchema,
57
123
  TenantsOwnershipSchema,
58
124
  VerboseStatusSchema,
59
125
  compressAndEncodeProfileToBase64,
60
126
  decodeAndDecompressProfileFromBase64,
127
+ fetchProfileJwks,
128
+ isCanonicalKeyVersion,
61
129
  licensedResourceFromUrlString,
130
+ loadProfileSignatureVerifierFromEnv,
131
+ parseProfileJwks,
132
+ parseProfileJwksUrl,
62
133
  permissionFromInt,
63
134
  permissionToInt,
135
+ prepareProfileSignatureVerifier,
136
+ profileHeaderHash,
137
+ readJwksCacheMaxAge,
138
+ readSignatureKeyVersion,
64
139
  safeDecodeAndDecompressProfileFromBase64,
65
140
  tenantOwnershipFromUrlString,
66
141
  toLicensesVector,
67
- toOwnershipVector
142
+ toOwnershipVector,
143
+ verifyAndDecodeProfile,
144
+ verifyProfileSignature,
145
+ verifyRequestProfile
68
146
  };
69
147
  //# sourceMappingURL=index.js.map
@@ -1,4 +1,6 @@
1
+ import { IncomingMessage } from 'node:http';
1
2
  import { z } from 'zod';
3
+ import { KeyObject } from 'node:crypto';
2
4
 
3
5
  declare const KNOWN_KEYS: readonly ["phone_number", "telegram_user", "whatsapp_user", "locale"];
4
6
  type AccountMetaKey = (typeof KNOWN_KEYS)[number] | `custom:${string}`;
@@ -6,15 +8,6 @@ declare const AccountMetaKeySchema: z.ZodEffects<z.ZodString, AccountMetaKey, st
6
8
  declare const ProfileMetaSchema: z.ZodRecord<z.ZodEffects<z.ZodString, AccountMetaKey, string>, z.ZodString>;
7
9
  type ProfileMeta = z.infer<typeof ProfileMetaSchema>;
8
10
 
9
- declare const Permission: {
10
- readonly READ: 0;
11
- readonly WRITE: 1;
12
- };
13
- type Permission = (typeof Permission)[keyof typeof Permission];
14
- declare const PermissionSchema: z.ZodType<Permission>;
15
- declare function permissionToInt(permission: Permission): number;
16
- declare function permissionFromInt(value: number): Permission;
17
-
18
11
  declare const LicensedResourceSchema: z.ZodObject<{
19
12
  accId: z.ZodString;
20
13
  sysAcc: z.ZodBoolean;
@@ -22,7 +15,7 @@ declare const LicensedResourceSchema: z.ZodObject<{
22
15
  accName: z.ZodString;
23
16
  role: z.ZodString;
24
17
  roleId: z.ZodString;
25
- perm: z.ZodType<Permission, z.ZodTypeDef, Permission>;
18
+ perm: z.ZodUnion<[z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodEffects<z.ZodLiteral<"read">, 0, "read">, z.ZodEffects<z.ZodLiteral<"write">, 1, "write">]>;
26
19
  verified: z.ZodBoolean;
27
20
  permitFlags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
28
21
  denyFlags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -34,7 +27,7 @@ declare const LicensedResourceSchema: z.ZodObject<{
34
27
  accName: string;
35
28
  role: string;
36
29
  roleId: string;
37
- perm: Permission;
30
+ perm: 0 | 1;
38
31
  permitFlags?: string[] | undefined;
39
32
  denyFlags?: string[] | undefined;
40
33
  }, {
@@ -45,7 +38,7 @@ declare const LicensedResourceSchema: z.ZodObject<{
45
38
  accName: string;
46
39
  role: string;
47
40
  roleId: string;
48
- perm: Permission;
41
+ perm: 0 | 1 | "read" | "write";
49
42
  permitFlags?: string[] | undefined;
50
43
  denyFlags?: string[] | undefined;
51
44
  }>;
@@ -61,7 +54,7 @@ declare const LicensedResourcesSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"kin
61
54
  accName: z.ZodString;
62
55
  role: z.ZodString;
63
56
  roleId: z.ZodString;
64
- perm: z.ZodType<Permission, z.ZodTypeDef, Permission>;
57
+ perm: z.ZodUnion<[z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodEffects<z.ZodLiteral<"read">, 0, "read">, z.ZodEffects<z.ZodLiteral<"write">, 1, "write">]>;
65
58
  verified: z.ZodBoolean;
66
59
  permitFlags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
67
60
  denyFlags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -73,7 +66,7 @@ declare const LicensedResourcesSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"kin
73
66
  accName: string;
74
67
  role: string;
75
68
  roleId: string;
76
- perm: Permission;
69
+ perm: 0 | 1;
77
70
  permitFlags?: string[] | undefined;
78
71
  denyFlags?: string[] | undefined;
79
72
  }, {
@@ -84,7 +77,7 @@ declare const LicensedResourcesSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"kin
84
77
  accName: string;
85
78
  role: string;
86
79
  roleId: string;
87
- perm: Permission;
80
+ perm: 0 | 1 | "read" | "write";
88
81
  permitFlags?: string[] | undefined;
89
82
  denyFlags?: string[] | undefined;
90
83
  }>, "many">;
@@ -97,7 +90,7 @@ declare const LicensedResourcesSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"kin
97
90
  accName: string;
98
91
  role: string;
99
92
  roleId: string;
100
- perm: Permission;
93
+ perm: 0 | 1;
101
94
  permitFlags?: string[] | undefined;
102
95
  denyFlags?: string[] | undefined;
103
96
  }[];
@@ -111,7 +104,7 @@ declare const LicensedResourcesSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"kin
111
104
  accName: string;
112
105
  role: string;
113
106
  roleId: string;
114
- perm: Permission;
107
+ perm: 0 | 1 | "read" | "write";
115
108
  permitFlags?: string[] | undefined;
116
109
  denyFlags?: string[] | undefined;
117
110
  }[];
@@ -134,7 +127,7 @@ declare const LicensedResourcesSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"kin
134
127
  accName: string;
135
128
  role: string;
136
129
  roleId: string;
137
- perm: Permission;
130
+ perm: 0 | 1;
138
131
  permitFlags?: string[] | undefined;
139
132
  denyFlags?: string[] | undefined;
140
133
  }[];
@@ -146,6 +139,15 @@ declare const LicensedResourcesSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"kin
146
139
  type LicensedResources = z.infer<typeof LicensedResourcesSchema>;
147
140
  declare function toLicensesVector(lr: LicensedResources | undefined): LicensedResource[];
148
141
 
142
+ declare const Permission: {
143
+ readonly READ: 0;
144
+ readonly WRITE: 1;
145
+ };
146
+ type Permission = (typeof Permission)[keyof typeof Permission];
147
+ declare const PermissionSchema: z.ZodUnion<[z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodEffects<z.ZodLiteral<"read">, 0, "read">, z.ZodEffects<z.ZodLiteral<"write">, 1, "write">]>;
148
+ declare function permissionToInt(permission: Permission): number;
149
+ declare function permissionFromInt(value: number): Permission;
150
+
149
151
  type RelatedAccounts = {
150
152
  kind: "AllowedAccounts";
151
153
  accounts: string[];
@@ -190,7 +192,7 @@ declare const ProfileSchema: z.ZodObject<{
190
192
  accountWasApproved: z.ZodBoolean;
191
193
  accountWasArchived: z.ZodBoolean;
192
194
  accountWasDeleted: z.ZodBoolean;
193
- verboseStatus: z.ZodOptional<z.ZodEnum<["unverified", "verified", "inactive", "archived", "deleted", "unknown"]>>;
195
+ verboseStatus: z.ZodOptional<z.ZodNullable<z.ZodEnum<["unverified", "verified", "inactive", "archived", "deleted", "unknown"]>>>;
194
196
  licensedResources: z.ZodOptional<z.ZodEffects<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
195
197
  kind: z.ZodLiteral<"records">;
196
198
  records: z.ZodArray<z.ZodObject<{
@@ -200,7 +202,7 @@ declare const ProfileSchema: z.ZodObject<{
200
202
  accName: z.ZodString;
201
203
  role: z.ZodString;
202
204
  roleId: z.ZodString;
203
- perm: z.ZodType<Permission, z.ZodTypeDef, Permission>;
205
+ perm: z.ZodUnion<[z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodEffects<z.ZodLiteral<"read">, 0, "read">, z.ZodEffects<z.ZodLiteral<"write">, 1, "write">]>;
204
206
  verified: z.ZodBoolean;
205
207
  permitFlags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
206
208
  denyFlags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -212,7 +214,7 @@ declare const ProfileSchema: z.ZodObject<{
212
214
  accName: string;
213
215
  role: string;
214
216
  roleId: string;
215
- perm: Permission;
217
+ perm: 0 | 1;
216
218
  permitFlags?: string[] | undefined;
217
219
  denyFlags?: string[] | undefined;
218
220
  }, {
@@ -223,7 +225,7 @@ declare const ProfileSchema: z.ZodObject<{
223
225
  accName: string;
224
226
  role: string;
225
227
  roleId: string;
226
- perm: Permission;
228
+ perm: 0 | 1 | "read" | "write";
227
229
  permitFlags?: string[] | undefined;
228
230
  denyFlags?: string[] | undefined;
229
231
  }>, "many">;
@@ -236,7 +238,7 @@ declare const ProfileSchema: z.ZodObject<{
236
238
  accName: string;
237
239
  role: string;
238
240
  roleId: string;
239
- perm: Permission;
241
+ perm: 0 | 1;
240
242
  permitFlags?: string[] | undefined;
241
243
  denyFlags?: string[] | undefined;
242
244
  }[];
@@ -250,7 +252,7 @@ declare const ProfileSchema: z.ZodObject<{
250
252
  accName: string;
251
253
  role: string;
252
254
  roleId: string;
253
- perm: Permission;
255
+ perm: 0 | 1 | "read" | "write";
254
256
  permitFlags?: string[] | undefined;
255
257
  denyFlags?: string[] | undefined;
256
258
  }[];
@@ -273,7 +275,7 @@ declare const ProfileSchema: z.ZodObject<{
273
275
  accName: string;
274
276
  role: string;
275
277
  roleId: string;
276
- perm: Permission;
278
+ perm: 0 | 1;
277
279
  permitFlags?: string[] | undefined;
278
280
  denyFlags?: string[] | undefined;
279
281
  }[];
@@ -351,7 +353,7 @@ declare const ProfileSchema: z.ZodObject<{
351
353
  accountWasApproved: boolean;
352
354
  accountWasArchived: boolean;
353
355
  accountWasDeleted: boolean;
354
- verboseStatus?: "unknown" | "unverified" | "verified" | "inactive" | "archived" | "deleted" | undefined;
356
+ verboseStatus?: "unknown" | "unverified" | "verified" | "inactive" | "archived" | "deleted" | null | undefined;
355
357
  licensedResources?: {
356
358
  records: {
357
359
  verified: boolean;
@@ -361,7 +363,7 @@ declare const ProfileSchema: z.ZodObject<{
361
363
  accName: string;
362
364
  role: string;
363
365
  roleId: string;
364
- perm: Permission;
366
+ perm: 0 | 1;
365
367
  permitFlags?: string[] | undefined;
366
368
  denyFlags?: string[] | undefined;
367
369
  }[];
@@ -401,7 +403,7 @@ declare const ProfileSchema: z.ZodObject<{
401
403
  username?: string | undefined;
402
404
  }[] | undefined;
403
405
  isManager?: boolean | undefined;
404
- verboseStatus?: "unknown" | "unverified" | "verified" | "inactive" | "archived" | "deleted" | undefined;
406
+ verboseStatus?: "unknown" | "unverified" | "verified" | "inactive" | "archived" | "deleted" | null | undefined;
405
407
  licensedResources?: unknown;
406
408
  tenantsOwnership?: unknown;
407
409
  meta?: Record<string, string> | undefined;
@@ -460,4 +462,107 @@ declare class Profile {
460
462
  profileRedacted(): string;
461
463
  }
462
464
 
463
- export { type AccountMetaKey as A, type LicensedResource as L, Profile as P, type RelatedAccounts as R, AccountMetaKeySchema as a, LicensedResourceSchema as b, type LicensedResources as c, LicensedResourcesSchema as d, Permission as e, PermissionSchema as f, type ProfileData as g, type ProfileMeta as h, ProfileMetaSchema as i, ProfileSchema as j, permissionToInt as k, licensedResourceFromUrlString as l, permissionFromInt as p, toLicensesVector as t };
465
+ /** A key set read from the gateway, with how long it may be cached. */
466
+ interface FetchedProfileJwks {
467
+ keys: ReadonlyMap<string, KeyObject>;
468
+ maxAgeSeconds: number;
469
+ }
470
+ /** How the key store downloads the JWKS (HTTP in production, fakes in tests). */
471
+ type ProfileJwksFetcher = (url: URL) => Promise<FetchedProfileJwks>;
472
+ declare class ProfileJwksFetchError extends Error {
473
+ constructor(problem: string);
474
+ }
475
+ /**
476
+ * Download and parse the gateway profile JWKS over HTTP.
477
+ *
478
+ * Bounded: 5 s timeout, 64 KiB body, redirects never followed (a redirect
479
+ * could move the trust anchor to another origin). The cache lifetime comes
480
+ * from `Cache-Control: max-age` (see `readJwksCacheMaxAge`).
481
+ */
482
+ declare const fetchProfileJwks: ProfileJwksFetcher;
483
+
484
+ /** Milliseconds clock, injectable for tests. */
485
+ type MonotonicClock = () => number;
486
+ interface CachedProfileKeys {
487
+ keys: ReadonlyMap<string, KeyObject>;
488
+ generation: number;
489
+ }
490
+ /**
491
+ * The gateway public keys cached by a downstream verifier.
492
+ *
493
+ * - Fetched lazily on the first request (default) or before serving
494
+ * (`prefetch`, opt-in). Until a set is downloaded, requests fail closed and
495
+ * the fetch is retried at most every `PROFILE_JWKS_EMPTY_RETRY_SECONDS`, so
496
+ * a service started before the gateway recovers within seconds.
497
+ * - Refreshed when `max-age` expires; a failed refresh keeps the last valid
498
+ * set and logs a warning, so a short gateway outage never drops trusted
499
+ * keys. The set stops being trusted `PROFILE_JWKS_MAX_STALE_SECONDS` after
500
+ * it expired, so a retired key cannot verify forever while refreshes fail.
501
+ * - A request never waits for a refresh another request already started
502
+ * while keys are cached: it verifies with the cached set.
503
+ * - Refetched once when a signature names an unknown `kid`, at most once per
504
+ * cooldown (measured from the end of the last attempt), and single-flight:
505
+ * concurrent requests share one fetch, and waiters that see a newer
506
+ * generation reuse it without fetching again.
507
+ */
508
+ declare class ProfileKeyStore {
509
+ #private;
510
+ constructor(url: URL, fetcher: ProfileJwksFetcher, cooldownSeconds: number, clock?: MonotonicClock);
511
+ get url(): URL;
512
+ /** The trusted keys now, and the generation they belong to. */
513
+ current(): CachedProfileKeys;
514
+ /** Fetch the set now; any failure rejects (startup must abort). */
515
+ prefetch(): Promise<void>;
516
+ /** Refresh when the cached set expired (or was never fetched). */
517
+ refreshIfStale(): Promise<void>;
518
+ /** Refetch after an unknown `kid`; `true` when newer keys are available. */
519
+ refreshAfterUnknownKey(seenGeneration: number): Promise<boolean>;
520
+ }
521
+
522
+ /**
523
+ * Downstream verifier whose trusted keys come from the gateway JWKS.
524
+ *
525
+ * Enabled by `MYCELIUM_JWKS_URL`; the expected audience is mandatory, so a
526
+ * signed pair issued for another service is always refused. Verification is
527
+ * the shared, local contract; only the keys are remote, refreshed as
528
+ * described in `ProfileKeyStore`. Build it with
529
+ * `prepareProfileSignatureVerifier()` (downloads the keys before serving) or
530
+ * `loadProfileSignatureVerifierFromEnv()` (keys fetched on first use).
531
+ */
532
+ declare class JwksProfileSignatureVerifier {
533
+ #private;
534
+ readonly store: ProfileKeyStore;
535
+ readonly toleranceSeconds: number;
536
+ readonly expectedAudience: string;
537
+ constructor(store: ProfileKeyStore, toleranceSeconds: number, expectedAudience: string);
538
+ /** Download the key set before serving; rejects when it cannot. */
539
+ prefetch(): Promise<void>;
540
+ /**
541
+ * Verify the signed profile, refetching the JWKS once on an unknown,
542
+ * canonical `kid`. Rejects with `ProfileSignatureError` like
543
+ * `verifyAndDecodeProfile`.
544
+ */
545
+ verifyAndDecode(profileHeader: string, signatureHeader: string, nowSeconds?: number): Promise<Profile>;
546
+ }
547
+
548
+ declare const SIGNATURE_REJECTION_DETAIL = "Unable to verify Mycelium profile";
549
+ declare const SIGNATURE_INTERNAL_DETAIL = "Unable to check user identity. Please contact administrators";
550
+ /** Log-safe reason only. Result ignored; returned promises are awaited safely. */
551
+ type SignatureRejectionListener = (reason: string) => unknown;
552
+ type SignatureVerificationOutcome = {
553
+ ok: true;
554
+ profile: Profile;
555
+ } | {
556
+ ok: false;
557
+ status: 403 | 500;
558
+ detail: string;
559
+ };
560
+ /**
561
+ * Authenticate and decode the profile carried by a request.
562
+ *
563
+ * Never throws: rejections map to 403, anything unexpected to 500, both with
564
+ * generic details. The caller must not run the handler unless `ok`.
565
+ */
566
+ declare function verifyRequestProfile(message: IncomingMessage, verifier: JwksProfileSignatureVerifier, onRejected?: SignatureRejectionListener): Promise<SignatureVerificationOutcome>;
567
+
568
+ export { type AccountMetaKey as A, type CachedProfileKeys as C, type FetchedProfileJwks as F, JwksProfileSignatureVerifier as J, type LicensedResource as L, type MonotonicClock as M, Profile as P, type RelatedAccounts as R, type SignatureRejectionListener as S, type ProfileJwksFetcher as a, AccountMetaKeySchema as b, LicensedResourceSchema as c, type LicensedResources as d, LicensedResourcesSchema as e, Permission as f, PermissionSchema as g, type ProfileData as h, ProfileJwksFetchError as i, ProfileKeyStore as j, type ProfileMeta as k, ProfileMetaSchema as l, ProfileSchema as m, SIGNATURE_INTERNAL_DETAIL as n, SIGNATURE_REJECTION_DETAIL as o, type SignatureVerificationOutcome as p, fetchProfileJwks as q, licensedResourceFromUrlString as r, permissionFromInt as s, permissionToInt as t, toLicensesVector as u, verifyRequestProfile as v };