@gadicc/loom 1.34.0 → 1.35.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/README.md +126 -49
- package/esm/src/apiKeys/authorize.d.ts.map +1 -1
- package/esm/src/apiKeys/authorize.js +71 -0
- package/esm/src/apiKeys/betterAuth.d.ts +123 -0
- package/esm/src/apiKeys/betterAuth.d.ts.map +1 -0
- package/esm/src/apiKeys/betterAuth.js +164 -0
- package/esm/src/apiKeys/credentials.d.ts +37 -2
- package/esm/src/apiKeys/credentials.d.ts.map +1 -1
- package/esm/src/apiKeys/credentials.js +69 -8
- package/esm/src/apiKeys/lifecycle.d.ts +41 -0
- package/esm/src/apiKeys/lifecycle.d.ts.map +1 -0
- package/esm/src/apiKeys/lifecycle.js +6 -0
- package/esm/src/apiKeys/limits.d.ts +132 -0
- package/esm/src/apiKeys/limits.d.ts.map +1 -0
- package/esm/src/apiKeys/limits.js +246 -0
- package/esm/src/apiKeys/mod.d.ts +4 -0
- package/esm/src/apiKeys/mod.d.ts.map +1 -1
- package/esm/src/apiKeys/mod.js +4 -0
- package/esm/src/apiKeys/permissions.d.ts +56 -0
- package/esm/src/apiKeys/permissions.d.ts.map +1 -0
- package/esm/src/apiKeys/permissions.js +128 -0
- package/esm/src/apiKeys/policy.d.ts +3 -1
- package/esm/src/apiKeys/policy.d.ts.map +1 -1
- package/esm/src/apiKeys/policy.js +3 -1
- package/esm/src/apiKeys/types.d.ts +68 -1
- package/esm/src/apiKeys/types.d.ts.map +1 -1
- package/esm/src/cli/localDevLock.d.ts +97 -0
- package/esm/src/cli/localDevLock.d.ts.map +1 -0
- package/esm/src/cli/localDevLock.js +312 -0
- package/esm/src/cli/localDevPackage.d.ts +172 -0
- package/esm/src/cli/localDevPackage.d.ts.map +1 -0
- package/esm/src/cli/localDevPackage.js +617 -0
- package/esm/src/cli/migrationEnv.d.ts +19 -0
- package/esm/src/cli/migrationEnv.d.ts.map +1 -1
- package/esm/src/cli/migrationEnv.js +44 -1
- package/esm/src/cli/mod.d.ts +69 -4
- package/esm/src/cli/mod.d.ts.map +1 -1
- package/esm/src/cli/mod.js +3060 -451
- package/esm/src/cli/projectTooling.d.ts +19 -1
- package/esm/src/cli/projectTooling.d.ts.map +1 -1
- package/esm/src/cli/projectTooling.js +142 -12
- package/esm/src/mui/apiKeys.d.ts +123 -17
- package/esm/src/mui/apiKeys.d.ts.map +1 -1
- package/esm/src/mui/apiKeys.js +219 -78
- package/esm/src/mui/apiKeysView.d.ts +145 -0
- package/esm/src/mui/apiKeysView.d.ts.map +1 -1
- package/esm/src/mui/apiKeysView.js +278 -0
- package/esm/src/next/apiKeys/mod.d.ts +8 -1
- package/esm/src/next/apiKeys/mod.d.ts.map +1 -1
- package/esm/src/next/apiKeys/mod.js +5 -2
- package/package.json +2 -6
- package/script/src/apiKeys/authorize.d.ts.map +1 -1
- package/script/src/apiKeys/authorize.js +71 -0
- package/script/src/apiKeys/betterAuth.d.ts +123 -0
- package/script/src/apiKeys/betterAuth.d.ts.map +1 -0
- package/script/src/apiKeys/betterAuth.js +169 -0
- package/script/src/apiKeys/credentials.d.ts +37 -2
- package/script/src/apiKeys/credentials.d.ts.map +1 -1
- package/script/src/apiKeys/credentials.js +71 -8
- package/script/src/apiKeys/lifecycle.d.ts +41 -0
- package/script/src/apiKeys/lifecycle.d.ts.map +1 -0
- package/script/src/apiKeys/lifecycle.js +7 -0
- package/script/src/apiKeys/limits.d.ts +132 -0
- package/script/src/apiKeys/limits.d.ts.map +1 -0
- package/script/src/apiKeys/limits.js +254 -0
- package/script/src/apiKeys/mod.d.ts +4 -0
- package/script/src/apiKeys/mod.d.ts.map +1 -1
- package/script/src/apiKeys/mod.js +4 -0
- package/script/src/apiKeys/permissions.d.ts +56 -0
- package/script/src/apiKeys/permissions.d.ts.map +1 -0
- package/script/src/apiKeys/permissions.js +136 -0
- package/script/src/apiKeys/policy.d.ts +3 -1
- package/script/src/apiKeys/policy.d.ts.map +1 -1
- package/script/src/apiKeys/policy.js +3 -1
- package/script/src/apiKeys/types.d.ts +68 -1
- package/script/src/apiKeys/types.d.ts.map +1 -1
- package/script/src/cli/localDevLock.d.ts +97 -0
- package/script/src/cli/localDevLock.d.ts.map +1 -0
- package/script/src/cli/localDevLock.js +320 -0
- package/script/src/cli/localDevPackage.d.ts +172 -0
- package/script/src/cli/localDevPackage.d.ts.map +1 -0
- package/script/src/cli/localDevPackage.js +635 -0
- package/script/src/cli/migrationEnv.d.ts +19 -0
- package/script/src/cli/migrationEnv.d.ts.map +1 -1
- package/script/src/cli/migrationEnv.js +48 -1
- package/script/src/cli/mod.d.ts +69 -4
- package/script/src/cli/mod.d.ts.map +1 -1
- package/script/src/cli/mod.js +3061 -451
- package/script/src/cli/projectTooling.d.ts +19 -1
- package/script/src/cli/projectTooling.d.ts.map +1 -1
- package/script/src/cli/projectTooling.js +176 -12
- package/script/src/mui/apiKeys.d.ts +123 -17
- package/script/src/mui/apiKeys.d.ts.map +1 -1
- package/script/src/mui/apiKeys.js +220 -77
- package/script/src/mui/apiKeysView.d.ts +145 -0
- package/script/src/mui/apiKeysView.d.ts.map +1 -1
- package/script/src/mui/apiKeysView.js +291 -0
- package/script/src/next/apiKeys/mod.d.ts +8 -1
- package/script/src/next/apiKeys/mod.d.ts.map +1 -1
- package/script/src/next/apiKeys/mod.js +5 -2
- package/skills/loom/SKILL.md +125 -18
- package/skills/loom-api-keys/SKILL.md +101 -7
- package/skills/loom-auth/SKILL.md +9 -0
- package/skills/loom-db/SKILL.md +3 -1
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
import type { ApiKeyScopeDefinitions, DefinedApiKeyScopes } from "./policy.js";
|
|
2
|
+
import type { ApiKeyPermission } from "./types.js";
|
|
3
|
+
/** Native Better Auth api-key permissions: resource name to action list. */
|
|
4
|
+
export type ApiKeyPermissionRecord = Record<string, string[]>;
|
|
5
|
+
type ScopeId<TDefinitions extends ApiKeyScopeDefinitions> = Extract<keyof TDefinitions, string>;
|
|
6
|
+
/**
|
|
7
|
+
* Reports whether decoded api-key permissions grant exactly `permission`.
|
|
8
|
+
*
|
|
9
|
+
* `decoded` must already be decoded: Better Auth's `verifyApiKey` result, or a
|
|
10
|
+
* raw column passed through `decodeStoredApiKeyPermissions`. Strings are never
|
|
11
|
+
* decoded here, because Better Auth has already decoded the column once; a
|
|
12
|
+
* string at this point means double-encoded storage, which Better Auth's own
|
|
13
|
+
* check denies too.
|
|
14
|
+
*
|
|
15
|
+
* Fails closed: anything but a plain or null-prototype object, inherited
|
|
16
|
+
* properties, non-array action lists, and non-identical action strings never
|
|
17
|
+
* match. This is stricter than Better Auth's check, which reads inherited
|
|
18
|
+
* properties and would substring-match an action list stored as a string.
|
|
19
|
+
*/
|
|
20
|
+
export declare function hasApiKeyPermission(decoded: unknown, permission: ApiKeyPermission): boolean;
|
|
21
|
+
/**
|
|
22
|
+
* Decodes a raw stored `apikey.permissions` value exactly once.
|
|
23
|
+
*
|
|
24
|
+
* Better Auth stores permissions as JSON text. A string is parsed once, and
|
|
25
|
+
* malformed JSON yields `null`; any other value is returned unchanged so a
|
|
26
|
+
* database driver that already decoded the column still works. JSON that
|
|
27
|
+
* decodes to another string, i.e. double-encoded storage, is returned as that
|
|
28
|
+
* string and therefore grants nothing.
|
|
29
|
+
*/
|
|
30
|
+
export declare function decodeStoredApiKeyPermissions(stored: unknown): unknown;
|
|
31
|
+
/**
|
|
32
|
+
* Converts scope IDs into the native permissions to store on a new key.
|
|
33
|
+
*
|
|
34
|
+
* Actions for scopes that share a resource are merged rather than replaced,
|
|
35
|
+
* and duplicates are removed. An ID that is not an own registry entry throws:
|
|
36
|
+
* validate untrusted input against the registry first.
|
|
37
|
+
*/
|
|
38
|
+
export declare function apiKeyPermissionsFromScopeIds<TDefinitions extends ApiKeyScopeDefinitions>(registry: DefinedApiKeyScopes<TDefinitions>, scopeIds: readonly string[]): ApiKeyPermissionRecord;
|
|
39
|
+
/**
|
|
40
|
+
* Lists the registry scope IDs that decoded permissions grant exactly, in
|
|
41
|
+
* registry order. Grants outside the registry are ignored.
|
|
42
|
+
*/
|
|
43
|
+
export declare function apiKeyScopeIdsFromPermissions<TDefinitions extends ApiKeyScopeDefinitions>(registry: DefinedApiKeyScopes<TDefinitions>, decoded: unknown): ScopeId<TDefinitions>[];
|
|
44
|
+
/**
|
|
45
|
+
* Builds the explicit principal permissions for a verified key: the registry
|
|
46
|
+
* permissions that decoded permissions grant exactly, in registry order.
|
|
47
|
+
*/
|
|
48
|
+
export declare function apiKeyPrincipalPermissions<TDefinitions extends ApiKeyScopeDefinitions>(registry: DefinedApiKeyScopes<TDefinitions>, decoded: unknown): ApiKeyPermission[];
|
|
49
|
+
/**
|
|
50
|
+
* Flattens every exact grant in decoded permissions, for verifiers without a
|
|
51
|
+
* registry. Non-plain objects, inherited properties, non-array action lists,
|
|
52
|
+
* and non-string or empty actions are skipped.
|
|
53
|
+
*/
|
|
54
|
+
export declare function apiKeyGrantedPermissions(decoded: unknown): ApiKeyPermission[];
|
|
55
|
+
export {};
|
|
56
|
+
//# sourceMappingURL=permissions.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../../src/src/apiKeys/permissions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,4EAA4E;AAC5E,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AAE9D,KAAK,OAAO,CAAC,YAAY,SAAS,sBAAsB,IAAI,OAAO,CACjE,MAAM,YAAY,EAClB,MAAM,CACP,CAAC;AAaF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,gBAAgB,GAC3B,OAAO,CAST;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAOtE;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,YAAY,SAAS,sBAAsB,EAE3C,QAAQ,EAAE,mBAAmB,CAAC,YAAY,CAAC,EAC3C,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,sBAAsB,CAiBxB;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,YAAY,SAAS,sBAAsB,EAE3C,QAAQ,EAAE,mBAAmB,CAAC,YAAY,CAAC,EAC3C,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,YAAY,CAAC,EAAE,CAIzB;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,YAAY,SAAS,sBAAsB,EAE3C,QAAQ,EAAE,mBAAmB,CAAC,YAAY,CAAC,EAC3C,OAAO,EAAE,OAAO,GACf,gBAAgB,EAAE,CAOpB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,EAAE,CAe7E"}
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
|
|
2
|
+
/** Returns `value` only when it is a plain (JSON-shaped) object. */
|
|
3
|
+
function asPermissionRecord(value) {
|
|
4
|
+
if (!value || typeof value !== "object" || Array.isArray(value))
|
|
5
|
+
return null;
|
|
6
|
+
const prototype = Object.getPrototypeOf(value);
|
|
7
|
+
if (prototype !== Object.prototype && prototype !== null)
|
|
8
|
+
return null;
|
|
9
|
+
return value;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Reports whether decoded api-key permissions grant exactly `permission`.
|
|
13
|
+
*
|
|
14
|
+
* `decoded` must already be decoded: Better Auth's `verifyApiKey` result, or a
|
|
15
|
+
* raw column passed through `decodeStoredApiKeyPermissions`. Strings are never
|
|
16
|
+
* decoded here, because Better Auth has already decoded the column once; a
|
|
17
|
+
* string at this point means double-encoded storage, which Better Auth's own
|
|
18
|
+
* check denies too.
|
|
19
|
+
*
|
|
20
|
+
* Fails closed: anything but a plain or null-prototype object, inherited
|
|
21
|
+
* properties, non-array action lists, and non-identical action strings never
|
|
22
|
+
* match. This is stricter than Better Auth's check, which reads inherited
|
|
23
|
+
* properties and would substring-match an action list stored as a string.
|
|
24
|
+
*/
|
|
25
|
+
export function hasApiKeyPermission(decoded, permission) {
|
|
26
|
+
if (!permission || typeof permission !== "object")
|
|
27
|
+
return false;
|
|
28
|
+
const { action, resource } = permission;
|
|
29
|
+
if (typeof resource !== "string" || typeof action !== "string")
|
|
30
|
+
return false;
|
|
31
|
+
if (!resource || !action)
|
|
32
|
+
return false;
|
|
33
|
+
const record = asPermissionRecord(decoded);
|
|
34
|
+
if (!record || !hasOwn(record, resource))
|
|
35
|
+
return false;
|
|
36
|
+
const actions = record[resource];
|
|
37
|
+
return Array.isArray(actions) && actions.includes(action);
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Decodes a raw stored `apikey.permissions` value exactly once.
|
|
41
|
+
*
|
|
42
|
+
* Better Auth stores permissions as JSON text. A string is parsed once, and
|
|
43
|
+
* malformed JSON yields `null`; any other value is returned unchanged so a
|
|
44
|
+
* database driver that already decoded the column still works. JSON that
|
|
45
|
+
* decodes to another string, i.e. double-encoded storage, is returned as that
|
|
46
|
+
* string and therefore grants nothing.
|
|
47
|
+
*/
|
|
48
|
+
export function decodeStoredApiKeyPermissions(stored) {
|
|
49
|
+
if (typeof stored !== "string")
|
|
50
|
+
return stored;
|
|
51
|
+
try {
|
|
52
|
+
return JSON.parse(stored);
|
|
53
|
+
}
|
|
54
|
+
catch {
|
|
55
|
+
return null;
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Converts scope IDs into the native permissions to store on a new key.
|
|
60
|
+
*
|
|
61
|
+
* Actions for scopes that share a resource are merged rather than replaced,
|
|
62
|
+
* and duplicates are removed. An ID that is not an own registry entry throws:
|
|
63
|
+
* validate untrusted input against the registry first.
|
|
64
|
+
*/
|
|
65
|
+
export function apiKeyPermissionsFromScopeIds(registry, scopeIds) {
|
|
66
|
+
if (!Array.isArray(scopeIds)) {
|
|
67
|
+
throw new Error("API-key scope IDs must be an array.");
|
|
68
|
+
}
|
|
69
|
+
const actionsByResource = new Map();
|
|
70
|
+
for (const scopeId of scopeIds) {
|
|
71
|
+
if (typeof scopeId !== "string" || !hasOwn(registry.byId, scopeId)) {
|
|
72
|
+
throw new Error(`Unknown API-key scope "${String(scopeId)}".`);
|
|
73
|
+
}
|
|
74
|
+
const { action, resource } = registry.byId[scopeId].permission;
|
|
75
|
+
const actions = actionsByResource.get(resource) ?? [];
|
|
76
|
+
if (!actions.includes(action))
|
|
77
|
+
actions.push(action);
|
|
78
|
+
actionsByResource.set(resource, actions);
|
|
79
|
+
}
|
|
80
|
+
// `Object.fromEntries` defines own data properties, so a resource such as
|
|
81
|
+
// "__proto__" cannot change the result's prototype.
|
|
82
|
+
return Object.fromEntries(actionsByResource);
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* Lists the registry scope IDs that decoded permissions grant exactly, in
|
|
86
|
+
* registry order. Grants outside the registry are ignored.
|
|
87
|
+
*/
|
|
88
|
+
export function apiKeyScopeIdsFromPermissions(registry, decoded) {
|
|
89
|
+
return registry.list
|
|
90
|
+
.filter((scope) => hasApiKeyPermission(decoded, scope.permission))
|
|
91
|
+
.map((scope) => scope.id);
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* Builds the explicit principal permissions for a verified key: the registry
|
|
95
|
+
* permissions that decoded permissions grant exactly, in registry order.
|
|
96
|
+
*/
|
|
97
|
+
export function apiKeyPrincipalPermissions(registry, decoded) {
|
|
98
|
+
return registry.list
|
|
99
|
+
.filter((scope) => hasApiKeyPermission(decoded, scope.permission))
|
|
100
|
+
.map((scope) => ({
|
|
101
|
+
action: scope.permission.action,
|
|
102
|
+
resource: scope.permission.resource,
|
|
103
|
+
}));
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* Flattens every exact grant in decoded permissions, for verifiers without a
|
|
107
|
+
* registry. Non-plain objects, inherited properties, non-array action lists,
|
|
108
|
+
* and non-string or empty actions are skipped.
|
|
109
|
+
*/
|
|
110
|
+
export function apiKeyGrantedPermissions(decoded) {
|
|
111
|
+
const record = asPermissionRecord(decoded);
|
|
112
|
+
if (!record)
|
|
113
|
+
return [];
|
|
114
|
+
const permissions = [];
|
|
115
|
+
for (const resource of Object.keys(record)) {
|
|
116
|
+
const actions = record[resource];
|
|
117
|
+
if (!resource || !Array.isArray(actions))
|
|
118
|
+
continue;
|
|
119
|
+
const seen = new Set();
|
|
120
|
+
for (const action of actions) {
|
|
121
|
+
if (typeof action !== "string" || !action || seen.has(action))
|
|
122
|
+
continue;
|
|
123
|
+
seen.add(action);
|
|
124
|
+
permissions.push({ action, resource });
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
return permissions;
|
|
128
|
+
}
|
|
@@ -50,7 +50,9 @@ export declare function defineApiKeyScopes<const TDefinitions extends ApiKeyScop
|
|
|
50
50
|
* Creates an exact-match, default-deny policy from a typed scope registry.
|
|
51
51
|
*
|
|
52
52
|
* The verifier remains responsible for proving that the key owns the requested
|
|
53
|
-
* native permission
|
|
53
|
+
* native permission; for Better Auth, `createBetterAuthApiKeyVerifier` checks
|
|
54
|
+
* the decoded grants itself, because the plugin reports a missing permission
|
|
55
|
+
* as an unknown key. Dynamic rules are for fresh app-owned checks such as
|
|
54
56
|
* current role membership; thrown errors intentionally reach Loom's existing
|
|
55
57
|
* `policy_error` handling.
|
|
56
58
|
*/
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/src/apiKeys/policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,6BAA6B,EAC7B,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,gEAAgE;AAChE,MAAM,WAAW,qBAAqB;IACpC,kFAAkF;IAClF,UAAU,EAAE,gBAAgB,CAAC;CAC9B;AAED,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAC3C,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CACtC,CAAC;AAEF,KAAK,aAAa,CAAC,YAAY,SAAS,sBAAsB,IAAI,OAAO,CACvE,MAAM,YAAY,EAClB,MAAM,CACP,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,mBAAmB,CAC7B,YAAY,SAAS,sBAAsB,IACzC;KACD,GAAG,IAAI,aAAa,CAAC,YAAY,CAAC,GAAG,QAAQ,CAC5C;QAAE,EAAE,EAAE,GAAG,CAAA;KAAE,GAAG,YAAY,CAAC,GAAG,CAAC,CAChC;CACF,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC;AAE/B,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB,CAClC,YAAY,SAAS,sBAAsB;IAE3C,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,4CAA4C;IAC5C,QAAQ,CAAC,GAAG,EAAE,SAAS,aAAa,CAAC,YAAY,CAAC,EAAE,CAAC;IACrD,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,SAAS,mBAAmB,CAAC,YAAY,CAAC,EAAE,CAAC;IAC5D,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,EAAE,GAAG,IAAI,aAAa,CAAC,YAAY,CAAC,GAC1C,YAAY,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC;KAClC,CAAC;CACH;AAED,4DAA4D;AAC5D,MAAM,WAAW,uBAAuB;IACtC,uEAAuE;IACvE,UAAU,EAAE,6BAA6B,CAAC;IAC1C,gEAAgE;IAChE,SAAS,EAAE,eAAe,CAAC;CAC5B;AAED,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,GACxB,OAAO,GACP,MAAM,GACN,CAAC,CACD,OAAO,EAAE,uBAAuB,KAC7B,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAEzD,wEAAwE;AACxE,MAAM,MAAM,iBAAiB,CAC3B,YAAY,SAAS,sBAAsB,IACzC;IACF,QAAQ,EAAE,GAAG,IAAI,aAAa,CAAC,YAAY,CAAC,GAAG,gBAAgB;CAChE,CAAC;AA+CF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,YAAY,SAAS,sBAAsB,EACjD,WAAW,EAAE,YAAY,GAAG,mBAAmB,CAAC,YAAY,CAAC,CAkB9D;AAsBD
|
|
1
|
+
{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/src/apiKeys/policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,6BAA6B,EAC7B,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,gEAAgE;AAChE,MAAM,WAAW,qBAAqB;IACpC,kFAAkF;IAClF,UAAU,EAAE,gBAAgB,CAAC;CAC9B;AAED,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAC3C,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CACtC,CAAC;AAEF,KAAK,aAAa,CAAC,YAAY,SAAS,sBAAsB,IAAI,OAAO,CACvE,MAAM,YAAY,EAClB,MAAM,CACP,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,mBAAmB,CAC7B,YAAY,SAAS,sBAAsB,IACzC;KACD,GAAG,IAAI,aAAa,CAAC,YAAY,CAAC,GAAG,QAAQ,CAC5C;QAAE,EAAE,EAAE,GAAG,CAAA;KAAE,GAAG,YAAY,CAAC,GAAG,CAAC,CAChC;CACF,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC;AAE/B,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB,CAClC,YAAY,SAAS,sBAAsB;IAE3C,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,4CAA4C;IAC5C,QAAQ,CAAC,GAAG,EAAE,SAAS,aAAa,CAAC,YAAY,CAAC,EAAE,CAAC;IACrD,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,SAAS,mBAAmB,CAAC,YAAY,CAAC,EAAE,CAAC;IAC5D,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,EAAE,GAAG,IAAI,aAAa,CAAC,YAAY,CAAC,GAC1C,YAAY,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC;KAClC,CAAC;CACH;AAED,4DAA4D;AAC5D,MAAM,WAAW,uBAAuB;IACtC,uEAAuE;IACvE,UAAU,EAAE,6BAA6B,CAAC;IAC1C,gEAAgE;IAChE,SAAS,EAAE,eAAe,CAAC;CAC5B;AAED,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,GACxB,OAAO,GACP,MAAM,GACN,CAAC,CACD,OAAO,EAAE,uBAAuB,KAC7B,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAEzD,wEAAwE;AACxE,MAAM,MAAM,iBAAiB,CAC3B,YAAY,SAAS,sBAAsB,IACzC;IACF,QAAQ,EAAE,GAAG,IAAI,aAAa,CAAC,YAAY,CAAC,GAAG,gBAAgB;CAChE,CAAC;AA+CF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,YAAY,SAAS,sBAAsB,EACjD,WAAW,EAAE,YAAY,GAAG,mBAAmB,CAAC,YAAY,CAAC,CAkB9D;AAsBD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,YAAY,SAAS,sBAAsB,EAEjD,QAAQ,EAAE,mBAAmB,CAAC,YAAY,CAAC,EAC3C,KAAK,EAAE,iBAAiB,CAAC,YAAY,CAAC,GACrC,YAAY,CAiBd"}
|
|
@@ -65,7 +65,9 @@ function assertPolicyRules(registry, rules) {
|
|
|
65
65
|
* Creates an exact-match, default-deny policy from a typed scope registry.
|
|
66
66
|
*
|
|
67
67
|
* The verifier remains responsible for proving that the key owns the requested
|
|
68
|
-
* native permission
|
|
68
|
+
* native permission; for Better Auth, `createBetterAuthApiKeyVerifier` checks
|
|
69
|
+
* the decoded grants itself, because the plugin reports a missing permission
|
|
70
|
+
* as an unknown key. Dynamic rules are for fresh app-owned checks such as
|
|
69
71
|
* current role membership; thrown errors intentionally reach Loom's existing
|
|
70
72
|
* `policy_error` handling.
|
|
71
73
|
*/
|
|
@@ -19,17 +19,32 @@ export type ApiKeyCredentialExtractionResult = {
|
|
|
19
19
|
transport: ApiKeyCredentialTransport;
|
|
20
20
|
} | {
|
|
21
21
|
kind: "ambiguous";
|
|
22
|
+
/**
|
|
23
|
+
* The transports involved. A single element means one transport carried
|
|
24
|
+
* several values, for example `["x-api-key"]` for a repeated header or
|
|
25
|
+
* `["query"]` for a repeated query parameter.
|
|
26
|
+
*/
|
|
22
27
|
transports: ApiKeyCredentialTransport[];
|
|
23
28
|
} | {
|
|
24
29
|
credential: string;
|
|
25
30
|
kind: "present";
|
|
26
31
|
transport: ApiKeyCredentialTransport;
|
|
27
32
|
};
|
|
33
|
+
/**
|
|
34
|
+
* Which credential transports an app accepts. Plain data, so the same object
|
|
35
|
+
* can configure the authorizer and, passed from a Server Component, the MUI
|
|
36
|
+
* transport guidance.
|
|
37
|
+
*/
|
|
28
38
|
export interface ApiKeyCredentialOptions {
|
|
39
|
+
/** Accept `Authorization: Bearer <key>`. Defaults to `true`. */
|
|
29
40
|
allowAuthorizationBearer?: boolean;
|
|
41
|
+
/** Accept a query parameter. Defaults to `false`; URLs leak keys. */
|
|
30
42
|
allowQuery?: boolean;
|
|
43
|
+
/** Accept the `xApiKeyHeaderName` header. Defaults to `true`. */
|
|
31
44
|
allowXApiKey?: boolean;
|
|
45
|
+
/** Query parameter name. Defaults to `"apiKey"`. */
|
|
32
46
|
queryName?: string;
|
|
47
|
+
/** Header name for the `x-api-key` transport. Defaults to `"x-api-key"`. */
|
|
33
48
|
xApiKeyHeaderName?: string;
|
|
34
49
|
}
|
|
35
50
|
export interface ApiKeyCredentialSource {
|
|
@@ -73,7 +88,7 @@ export interface ApiKeyAuthorizationAuditEvent {
|
|
|
73
88
|
operation: string;
|
|
74
89
|
ownerId?: string;
|
|
75
90
|
pageName?: string;
|
|
76
|
-
reasonCode?:
|
|
91
|
+
reasonCode?: ApiKeyAuditReasonCode;
|
|
77
92
|
requestId?: string;
|
|
78
93
|
routeTemplate?: string;
|
|
79
94
|
scopeAction: string;
|
|
@@ -98,6 +113,11 @@ export interface ApiKeyCompletionAuditEvent {
|
|
|
98
113
|
operationOutcome: ApiKeyOperationOutcome;
|
|
99
114
|
ownerId: string;
|
|
100
115
|
pageName?: string;
|
|
116
|
+
/**
|
|
117
|
+
* Loom records an `ApiKeyCompletionReasonCode`. The type stays `string` for
|
|
118
|
+
* completion events an app appends itself; never record error messages or
|
|
119
|
+
* class names here, because owners can read their own audit history.
|
|
120
|
+
*/
|
|
101
121
|
reasonCode?: string;
|
|
102
122
|
requestId?: string;
|
|
103
123
|
scopeAction: string;
|
|
@@ -134,6 +154,19 @@ export type ApiKeyVerifierResult = {
|
|
|
134
154
|
} | {
|
|
135
155
|
code: "insufficient_permission" | "invalid_credential" | "rate_limited";
|
|
136
156
|
ok: false;
|
|
157
|
+
/**
|
|
158
|
+
* The valid key's identity, for an `insufficient_permission` denial
|
|
159
|
+
* only. Loom records it on the denial audit event so the key's owner can
|
|
160
|
+
* see it; it never reaches the caller or the response. Ignored for every
|
|
161
|
+
* other code, so invalid, revoked, expired, and rate-limited attempts stay
|
|
162
|
+
* unattributed.
|
|
163
|
+
*
|
|
164
|
+
* Return it only after the secret itself was verified (its hash matched)
|
|
165
|
+
* and the key was confirmed enabled and unexpired. Otherwise an
|
|
166
|
+
* attacker's attempts could be attributed to a victim's key and evict its
|
|
167
|
+
* history from the per-key retention cap.
|
|
168
|
+
*/
|
|
169
|
+
principal?: ApiKeyPrincipal;
|
|
137
170
|
status?: 401 | 403 | 429;
|
|
138
171
|
};
|
|
139
172
|
/** App adapter that performs exactly one verification call per authorization. */
|
|
@@ -163,11 +196,45 @@ export type ApiKeyAuthorizationResult = {
|
|
|
163
196
|
ok: false;
|
|
164
197
|
status: 400 | 401 | 403 | 429 | 500 | 503;
|
|
165
198
|
};
|
|
199
|
+
/**
|
|
200
|
+
* Reason recorded on an authorization audit event. Adds two audit-only codes
|
|
201
|
+
* for the `rejectCredential` hook: `credential_rejected` (it denied the
|
|
202
|
+
* credential; callers see `invalid_credential`) and
|
|
203
|
+
* `credential_rejection_error` (it threw; callers see `verification_error`).
|
|
204
|
+
*/
|
|
205
|
+
export type ApiKeyAuditReasonCode = ApiKeyDenialCode | "credential_rejected" | "credential_rejection_error";
|
|
206
|
+
/**
|
|
207
|
+
* Reason Loom records on a completion audit event: `handler_error` when the
|
|
208
|
+
* protected handler threw. The error's class and message are never recorded.
|
|
209
|
+
*/
|
|
210
|
+
export type ApiKeyCompletionReasonCode = "handler_error";
|
|
211
|
+
/** Context passed to a `rejectCredential` hook. */
|
|
212
|
+
export interface ApiKeyCredentialRejectionContext {
|
|
213
|
+
/** The protected operation being authorized. */
|
|
214
|
+
descriptor: ApiKeyAuthorizationDescriptor;
|
|
215
|
+
/** The transport the credential arrived in. */
|
|
216
|
+
transport: ApiKeyCredentialTransport;
|
|
217
|
+
}
|
|
218
|
+
/**
|
|
219
|
+
* App-owned check that denies specific credential values, such as a
|
|
220
|
+
* scheduler's shared secret, before Loom fingerprints, verifies, or
|
|
221
|
+
* attributes them. Any result other than `false` denies; a thrown error
|
|
222
|
+
* fails closed as `verification_error` (audited as
|
|
223
|
+
* `credential_rejection_error`).
|
|
224
|
+
*/
|
|
225
|
+
export type ApiKeyCredentialRejector = (credential: string, context: ApiKeyCredentialRejectionContext) => boolean | Promise<boolean>;
|
|
166
226
|
export interface AuthorizeApiKeyOptions {
|
|
167
227
|
audit: ApiKeyAuditRepository;
|
|
168
228
|
credentialOptions?: ApiKeyCredentialOptions;
|
|
169
229
|
descriptor: ApiKeyAuthorizationDescriptor;
|
|
170
230
|
policy: ApiKeyPolicy;
|
|
231
|
+
/**
|
|
232
|
+
* Called once with the single extracted credential, before it is
|
|
233
|
+
* fingerprinted or verified. A rejection is answered exactly like an
|
|
234
|
+
* invalid key (401 `invalid_credential`) and audited without any
|
|
235
|
+
* credential-derived data under reason `credential_rejected`.
|
|
236
|
+
*/
|
|
237
|
+
rejectCredential?: ApiKeyCredentialRejector;
|
|
171
238
|
request?: ApiKeyRequestAuditContext;
|
|
172
239
|
source: ApiKeyCredentialSource;
|
|
173
240
|
verifier: ApiKeyVerifier;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/src/apiKeys/types.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/src/apiKeys/types.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
/** Who holds a local-dev sync lock, as recorded in the lock file. */
|
|
2
|
+
export type LocalDevLockHolder = {
|
|
3
|
+
hostname: string;
|
|
4
|
+
pid: number;
|
|
5
|
+
/** ISO timestamp of when the holder acquired the lock. */
|
|
6
|
+
startedAt: string;
|
|
7
|
+
/** Distinguishes holders that share a PID, such as two syncs in one process. */
|
|
8
|
+
token: string;
|
|
9
|
+
};
|
|
10
|
+
/** What a lock holder's work receives from {@link withLocalDevLock}. */
|
|
11
|
+
export type LocalDevLockHandle = {
|
|
12
|
+
/**
|
|
13
|
+
* Throws if this process no longer owns the lock, for example because it
|
|
14
|
+
* was paused long enough for a waiter to judge the lock abandoned. Call it
|
|
15
|
+
* before each step that changes files or packages; `changesMade` says
|
|
16
|
+
* whether earlier steps already changed something, which the message then
|
|
17
|
+
* owns up to. Read errors other than a missing lock are retried and then
|
|
18
|
+
* reported as themselves, not as a lost lock.
|
|
19
|
+
*/
|
|
20
|
+
assertHeld(changesMade?: boolean): Promise<void>;
|
|
21
|
+
/** Whether this process waited for another holder before acquiring. */
|
|
22
|
+
waited: boolean;
|
|
23
|
+
};
|
|
24
|
+
/** The process-signal surface the lock uses to release itself on exit. */
|
|
25
|
+
export type LocalDevLockSignalTarget = {
|
|
26
|
+
kill(pid: number, signal: string): unknown;
|
|
27
|
+
off(signal: string, listener: (signal: string) => void): unknown;
|
|
28
|
+
on(signal: string, listener: (signal: string) => void): unknown;
|
|
29
|
+
};
|
|
30
|
+
/** Tuning and test seams for {@link withLocalDevLock}. */
|
|
31
|
+
export type LocalDevLockOptions = {
|
|
32
|
+
/**
|
|
33
|
+
* Test seam: runs while this process holds the break lock, after it
|
|
34
|
+
* confirmed the stale lock and before removing it.
|
|
35
|
+
*/
|
|
36
|
+
beforeBreak?: () => Promise<void>;
|
|
37
|
+
/** How often the holder refreshes the lock's modification time. */
|
|
38
|
+
heartbeatMs?: number;
|
|
39
|
+
hostname?: string;
|
|
40
|
+
/** Reports whether a process on this host is still running. */
|
|
41
|
+
isProcessAlive?: (pid: number) => boolean;
|
|
42
|
+
now?: () => number;
|
|
43
|
+
/** Called once when another holder makes this process wait. */
|
|
44
|
+
onWait?: (holder: LocalDevLockHolder | null) => void;
|
|
45
|
+
pollMs?: number;
|
|
46
|
+
/** Signals that release the lock before the process exits. */
|
|
47
|
+
signals?: readonly string[];
|
|
48
|
+
/** Test seam replacing `process` for signal handling. */
|
|
49
|
+
signalTarget?: LocalDevLockSignalTarget;
|
|
50
|
+
sleep?: (ms: number) => Promise<void>;
|
|
51
|
+
/** How long a lock may go unrefreshed before any waiter breaks it. */
|
|
52
|
+
staleAfterMs?: number;
|
|
53
|
+
/** How long to wait for another holder before failing. */
|
|
54
|
+
timeoutMs?: number;
|
|
55
|
+
/** Test seam for the heartbeat's refresh of the lock file. */
|
|
56
|
+
touch?: (path: string) => Promise<void>;
|
|
57
|
+
};
|
|
58
|
+
/** Holders refresh the lock this often while they run. */
|
|
59
|
+
export declare const LOCAL_DEV_LOCK_HEARTBEAT_MS = 5000;
|
|
60
|
+
/**
|
|
61
|
+
* A lock nobody refreshed for this long is stale whatever its host or PID:
|
|
62
|
+
* its holder crashed, was killed, or is on a machine that went away.
|
|
63
|
+
*/
|
|
64
|
+
export declare const LOCAL_DEV_LOCK_STALE_AFTER_MS = 60000;
|
|
65
|
+
/**
|
|
66
|
+
* A holder on this host whose process still exists (paused with Ctrl-Z or
|
|
67
|
+
* stopped in a debugger, say) keeps its lock this long without refreshing.
|
|
68
|
+
*/
|
|
69
|
+
export declare const LOCAL_DEV_LOCK_LIVE_HOLDER_STALE_AFTER_MS: number;
|
|
70
|
+
/** Default wait for another sync; well beyond the stale thresholds. */
|
|
71
|
+
export declare const LOCAL_DEV_LOCK_TIMEOUT_MS: number;
|
|
72
|
+
/**
|
|
73
|
+
* Removes a stale lock while holding `<lock>.break`, so that waiters break
|
|
74
|
+
* a crashed lock one at a time. Each breaker re-reads the lock under the
|
|
75
|
+
* break lock and removes it only if it still has the stale content, so a
|
|
76
|
+
* later breaker can never remove the fresh lock a previous waiter created.
|
|
77
|
+
* Returns false when another process is breaking it; the caller re-checks.
|
|
78
|
+
*/
|
|
79
|
+
export declare function breakStaleLock(lockPath: string, staleText: string, options: {
|
|
80
|
+
beforeBreak?: () => Promise<void>;
|
|
81
|
+
now: () => number;
|
|
82
|
+
}): Promise<boolean>;
|
|
83
|
+
/**
|
|
84
|
+
* Runs `run` while holding an exclusive lock file, so concurrent Loom
|
|
85
|
+
* commands in one project do not rebuild and reinstall the linked package at
|
|
86
|
+
* the same time. A waiting process runs `run` after the holder finishes, so
|
|
87
|
+
* it re-checks freshness instead of repeating the work.
|
|
88
|
+
*
|
|
89
|
+
* The holder refreshes the lock's modification time every `heartbeatMs` and
|
|
90
|
+
* removes it on SIGHUP/SIGINT/SIGTERM. A waiter breaks a lock it has seen
|
|
91
|
+
* unrefreshed for `staleAfterMs`, whatever its host or PID, or sooner (after
|
|
92
|
+
* two missed heartbeats) when the lock is already older than that or its
|
|
93
|
+
* process is gone on this host. Waiting longer than `timeoutMs` fails with a
|
|
94
|
+
* message naming the holder and the lock file.
|
|
95
|
+
*/
|
|
96
|
+
export declare function withLocalDevLock<T>(lockPath: string, run: (lock: LocalDevLockHandle) => Promise<T>, options?: LocalDevLockOptions): Promise<T>;
|
|
97
|
+
//# sourceMappingURL=localDevLock.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"localDevLock.d.ts","sourceRoot":"","sources":["../../../src/src/cli/localDevLock.ts"],"names":[],"mappings":"AAOA,qEAAqE;AACrE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,wEAAwE;AACxE,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;;;;OAOG;IACH,UAAU,CAAC,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,uEAAuE;IACvE,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,0EAA0E;AAC1E,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3C,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC;IACjE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC;CACjE,CAAC;AAEF,0DAA0D;AAC1D,MAAM,MAAM,mBAAmB,GAAG;IAChC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAC1C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,KAAK,IAAI,CAAC;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,yDAAyD;IACzD,YAAY,CAAC,EAAE,wBAAwB,CAAC;IACxC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AACjD;;;GAGG;AACH,eAAO,MAAM,6BAA6B,QAAS,CAAC;AACpD;;;GAGG;AACH,eAAO,MAAM,yCAAyC,QAAa,CAAC;AACpE,uEAAuE;AACvE,eAAO,MAAM,yBAAyB,QAAc,CAAC;AAoFrD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,GAAG,EAAE,MAAM,MAAM,CAAA;CAAE,oBA2BlE;AAQD;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,OAAO,CAAC,CAAC,CAAC,EAC7C,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,CAAC,CAAC,CAqKZ"}
|