@gadicc/loom 1.34.0 → 1.35.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/README.md +108 -41
- 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 +2806 -437
- 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 +2807 -437
- 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 +111 -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
|
@@ -17,7 +17,8 @@ current-role policy, audit repository, lifecycle actions, and migrations.
|
|
|
17
17
|
- Replace the deny-all policy, verifier, audit repository, and lifecycle action
|
|
18
18
|
stubs before production.
|
|
19
19
|
- Install compatible matching `better-auth` and `@better-auth/api-key` versions.
|
|
20
|
-
Keep API-key sessions disabled and
|
|
20
|
+
Keep API-key sessions disabled and build the verifier with
|
|
21
|
+
`createBetterAuthApiKeyVerifier` (one `verifyApiKey()` call per request).
|
|
21
22
|
- Foundation installation does not authorize any existing HTTP surface.
|
|
22
23
|
- Enable jobs separately with
|
|
23
24
|
`loom api-keys integrate jobs --resource jobs --action execute`. The command
|
|
@@ -39,9 +40,80 @@ current-role policy, audit repository, lifecycle actions, and migrations.
|
|
|
39
40
|
local tests because Vercel geolocation headers are deployment-only.
|
|
40
41
|
- Derive recent use from the newest allowed authorization event, not Better
|
|
41
42
|
Auth's generic `lastRequest`. Map its IP/country into the MUI recent-use row
|
|
42
|
-
and map each audit event's IP/country into its audit row.
|
|
43
|
+
and map each audit event's IP/country into its audit row. Also map its
|
|
44
|
+
`reasonCode` and key name/start snapshots to `ApiKeyAuditRow.reasonCode`,
|
|
45
|
+
`keyName`, and `keyStart`, so owners can tell a scope miss from a policy
|
|
46
|
+
denial; never put credential values in these fields. Codes Loom does not
|
|
47
|
+
record show as "Other reason", never as is; pass `reason` to label an
|
|
48
|
+
app-specific code, and `showKey` once snapshots are mapped.
|
|
43
49
|
- Exercise denial, audit-outage, handler-failure, query-credential, and stream
|
|
44
50
|
behavior before enabling a route. Run `loom check` and app checks afterward.
|
|
51
|
+
- `@gadicc/loom/mui/apiKeys` needs `@mui/material` 6 or newer and React 19 for
|
|
52
|
+
its pending states, although the package's optional MUI peer stays `>=5` for
|
|
53
|
+
`mui/mail` and `mui/confirm`.
|
|
54
|
+
|
|
55
|
+
## Better Auth verifier and key lifecycle
|
|
56
|
+
|
|
57
|
+
- Use `createBetterAuthApiKeyVerifier({ auth, configId, scopes })`. It never
|
|
58
|
+
sends `permissions` to `verifyApiKey()`: the plugin reports a key that lacks
|
|
59
|
+
one as `KEY_NOT_FOUND`, which would audit a scope miss as
|
|
60
|
+
`invalid_credential`. It checks the exact grant itself and returns
|
|
61
|
+
`insufficient_permission` (403). `RATE_LIMITED` and `USAGE_EXCEEDED` (spent
|
|
62
|
+
`remaining` quota) become `rate_limited` (429); other rejections are
|
|
63
|
+
`invalid_credential` (401). Malformed results and owners fail closed as
|
|
64
|
+
`verification_error`.
|
|
65
|
+
- Scope misses and policy denials come from a genuine key, so their audit rows
|
|
66
|
+
carry the key ID, owner, and name/start snapshots; owners see them in their
|
|
67
|
+
own history. The shared verifier returns `principal` with
|
|
68
|
+
`insufficient_permission` for this, and custom verifiers may do the same, but
|
|
69
|
+
only after the secret itself was verified (hash matched) and the key was
|
|
70
|
+
confirmed enabled and unexpired. Otherwise an attacker's guesses could be
|
|
71
|
+
attributed to a victim's key and evict its history from the per-key cap. Loom
|
|
72
|
+
ignores `principal` for every other code, so invalid, revoked, expired, and
|
|
73
|
+
rate-limited attempts stay unattributed. Responses never include it.
|
|
74
|
+
- A scope miss still passes through the plugin's usage claim (`lastRequest`,
|
|
75
|
+
`requestCount`, `updatedAt`). Keep per-key rate limits and `remaining` quotas
|
|
76
|
+
disabled unless that is acceptable. The plugin masks internal failures such as
|
|
77
|
+
a database outage as `INVALID_API_KEY` (401, fail closed); monitor Better
|
|
78
|
+
Auth's "Failed to validate API key" log.
|
|
79
|
+
- Never decode verifier permissions again. For raw stored columns use
|
|
80
|
+
`decodeStoredApiKeyPermissions`, then `apiKeyScopeIdsFromPermissions`; build
|
|
81
|
+
new keys' permissions with `apiKeyPermissionsFromScopeIds`, which merges
|
|
82
|
+
actions per resource.
|
|
83
|
+
- Run the lifecycle only through server actions that call `auth.api.*`, and
|
|
84
|
+
disable the plugin's HTTP endpoints with
|
|
85
|
+
`disabledPaths: withBetterAuthApiKeyHttpPathsDisabled()` in the app's Better
|
|
86
|
+
Auth options. Otherwise any signed-in user can re-enable revoked keys, remove
|
|
87
|
+
expiry, or hard-delete keys. `loom check` warns, and `--production` fails,
|
|
88
|
+
when it cannot prove all five disabled in every `betterAuth()` call. Pass the
|
|
89
|
+
helper (imported from `@gadicc/loom/apiKeys`) directly as the `disabledPaths`
|
|
90
|
+
value, after any spreads, in the `betterAuth()` options or in a top-level
|
|
91
|
+
`const` options object in the auth module or one module it imports. A factory
|
|
92
|
+
must forward its options parameter into `betterAuth()`. Conditionals, filtered
|
|
93
|
+
lists, later unresolvable spreads, shadowed or mutated bindings, and extra
|
|
94
|
+
unproven instances all fail. Record `"betterAuthHttpEndpoints": "app-owned"`
|
|
95
|
+
only when the app deliberately serves and guards those endpoints itself. Add a
|
|
96
|
+
consumer drift test that lists `auth.api` endpoints under `/api-key/` that are
|
|
97
|
+
not server-only and asserts each is disabled.
|
|
98
|
+
- Upgrading an existing api-keys consumer to the Loom release with this check
|
|
99
|
+
makes `loom check --production` fail until `disabledPaths` is added. Add it in
|
|
100
|
+
the same change as the upgrade.
|
|
101
|
+
- Define one `ApiKeyLimits`. Pass `betterAuthApiKeyLimitOptions(limits)` to the
|
|
102
|
+
plugin, validate server-action input with `validateApiKeyName` and
|
|
103
|
+
`resolveApiKeyExpiresIn`, map leftover plugin rejections with
|
|
104
|
+
`betterAuthApiKeyInputErrorMessage`, and pass the same `limits` to the MUI
|
|
105
|
+
manager so dialogs show identical messages before the call. A `null` expiry
|
|
106
|
+
("Never") gets the plugin's `keyExpiration.defaultExpiresIn`; keep that `null`
|
|
107
|
+
when "Never" should mean never, or pass `allowNoExpiry: false` to both the
|
|
108
|
+
validator and the MUI manager.
|
|
109
|
+
- Next.js masks thrown Server Function messages in production. Return
|
|
110
|
+
`{ ok: false, message }` for user-correctable errors from `onCreate`,
|
|
111
|
+
`onRename`, and `onRevoke` instead of throwing; the MUI components display it
|
|
112
|
+
and keep the user's input. With result-form `onCreate`, pass
|
|
113
|
+
`thrownErrorMessages="generic"` so unexpected thrown errors show a generic
|
|
114
|
+
message instead of internal or masked text. Import `ApiKeyCreateActionResult`,
|
|
115
|
+
`ApiKeyMutationResult`, and the other result types in server actions from
|
|
116
|
+
`@gadicc/loom/apiKeys`, not from the client module `@gadicc/loom/mui/apiKeys`.
|
|
45
117
|
|
|
46
118
|
## Adding consumer scopes
|
|
47
119
|
|
|
@@ -60,9 +132,15 @@ current-role policy, audit repository, lifecycle actions, and migrations.
|
|
|
60
132
|
- Carry the verified principal into the handler and constrain user-owned data in
|
|
61
133
|
its database query. Do not fetch broadly and filter afterward; define global
|
|
62
134
|
data semantics explicitly and fail closed when ownership is ambiguous.
|
|
63
|
-
- Keep Bearer and `X-API-Key` as the default transports
|
|
64
|
-
only for routes whose consumer explicitly accepts
|
|
65
|
-
keep audit metadata allowlisted and free of
|
|
135
|
+
- Keep Bearer and `X-API-Key` as the default transports; recommend Bearer.
|
|
136
|
+
Enable query transport only for routes whose consumer explicitly accepts
|
|
137
|
+
URL-credential leakage, and keep audit metadata allowlisted and free of
|
|
138
|
+
credential-bearing values.
|
|
139
|
+
- Keep `ApiKeyCredentialOptions` in one small import-free module. Import it into
|
|
140
|
+
the authorizer dependencies and pass the same object as `credentialOptions` to
|
|
141
|
+
`ApiKeysManager` and `ApiKeyTransportGuidance`, so the UI never names a
|
|
142
|
+
transport the authorizer rejects. Do not hand-write transport copy;
|
|
143
|
+
`queryCredentialsEnabled` is deprecated.
|
|
66
144
|
- Do not silently expand existing keys when a scope is introduced. Require a
|
|
67
145
|
replacement key for increased authority.
|
|
68
146
|
- A new native resource/action value normally uses the existing Better Auth
|
|
@@ -80,13 +158,28 @@ current-role policy, audit repository, lifecycle actions, and migrations.
|
|
|
80
158
|
- Bearer and `X-API-Key` are enabled by default. Query credentials require an
|
|
81
159
|
explicit consumer opt-in and can leak through browser history, access logs,
|
|
82
160
|
copied links, and referrers.
|
|
83
|
-
- Reject multiple transports even when values match
|
|
161
|
+
- Reject multiple transports even when values match, and repeated credentials
|
|
162
|
+
within one transport (comma-joined `x-api-key` lines, a literal comma in a
|
|
163
|
+
Bearer token, or a repeated query parameter). Keys must never contain a comma.
|
|
164
|
+
Node keeps only the first of repeated `Authorization` lines, so that first
|
|
165
|
+
value is what Loom verifies.
|
|
166
|
+
- When an API-key route shares a URL or transport with another credential, such
|
|
167
|
+
as a cron handler's `Authorization: Bearer <CRON_SECRET>`, pass
|
|
168
|
+
`rejectCredential` in the authorizer dependencies instead of wrapping Loom's
|
|
169
|
+
route helpers. It runs before fingerprinting or verification, answers exactly
|
|
170
|
+
like an invalid key, and audits an unattributed `credential_rejected` row.
|
|
171
|
+
Compare secrets in constant time; a thrown error fails closed and is audited
|
|
172
|
+
as `credential_rejection_error`.
|
|
84
173
|
- Never log or persist plaintext keys, authorization headers, full URLs, query
|
|
85
174
|
strings, or arbitrary handler parameters.
|
|
86
175
|
- An allowed authorization audit event must be durable before execution. Denied
|
|
87
176
|
requests remain denied if denial auditing is unavailable.
|
|
88
177
|
- Completion events describe response creation for streaming responses; Loom
|
|
89
178
|
does not buffer streams to observe full consumption.
|
|
179
|
+
- A thrown handler error returns a generic 500 and a completion event with the
|
|
180
|
+
fixed `reasonCode: "handler_error"`. Loom neither records nor logs the error,
|
|
181
|
+
so log it inside the handler if operators need it; keep it out of the audit
|
|
182
|
+
row, which the key owner can read.
|
|
90
183
|
- On Vercel, prefer `vercelApiKeyRequestContext` to snapshot the platform-owned
|
|
91
184
|
IP and country headers with no lookup dependency. The headers are absent
|
|
92
185
|
locally and require special handling when another proxy fronts Vercel.
|
|
@@ -112,7 +205,8 @@ current-role policy, audit repository, lifecycle actions, and migrations.
|
|
|
112
205
|
HTTP, require explicit scheduler authentication; never create a public
|
|
113
206
|
maintenance route.
|
|
114
207
|
- Apply the age cutoff to unattributed denials. Apply the per-key cap only where
|
|
115
|
-
a key is attributed, retaining the newest request groups.
|
|
208
|
+
a key is attributed, retaining the newest request groups. Attributed scope
|
|
209
|
+
misses and policy denials count toward that cap.
|
|
116
210
|
- Monitor `complete`; retry or alert when the runner reaches its batch safety
|
|
117
211
|
bound. Record aggregate cleanup metrics outside the audit table.
|
|
118
212
|
- Override retention for documented legal, regulatory, contractual, incident, or
|
|
@@ -117,6 +117,15 @@ The route may wrap its handlers, for example to fail closed while a migration
|
|
|
117
117
|
completes, as long as one `toNextJsHandler(<instance>)` call supplies every
|
|
118
118
|
exported `GET` and `POST`.
|
|
119
119
|
|
|
120
|
+
## Plugin HTTP endpoints
|
|
121
|
+
|
|
122
|
+
Better Auth plugins can add session-authenticated HTTP endpoints that bypass the
|
|
123
|
+
app's own server actions. List those the app does not intend to serve in the
|
|
124
|
+
top-level `disabledPaths` option, relative to the auth base path; server-side
|
|
125
|
+
`auth.api.*` calls are unaffected. With the api-key plugin, use
|
|
126
|
+
`withBetterAuthApiKeyHttpPathsDisabled()` from `@gadicc/loom/apiKeys` (see the
|
|
127
|
+
`loom-api-keys` skill); `loom check` verifies it while API keys are active.
|
|
128
|
+
|
|
120
129
|
## Request-scoped sessions
|
|
121
130
|
|
|
122
131
|
`createRequestAuthSessionReaders` returns four readers. `getSession` and
|
package/skills/loom-db/SKILL.md
CHANGED
|
@@ -139,7 +139,9 @@ Use this skill when working on the shared DB stack from a consuming app.
|
|
|
139
139
|
role, and direct-vs-pooled endpoint, then authenticates with the selected URL
|
|
140
140
|
and checks the target database and schema privileges without printing
|
|
141
141
|
credentials. A present but invalid override must fail instead of silently
|
|
142
|
-
falling back.
|
|
142
|
+
falling back. `--connect` loads the app's `postgres` package, an optional Loom
|
|
143
|
+
peer that `loom add db` installs; without it the command says so instead of
|
|
144
|
+
reporting a connection failure.
|
|
143
145
|
- Once a dedicated direct URL has been provisioned, load it as
|
|
144
146
|
`MIGRATION_DATABASE_URL_UNPOOLED` in the local process and run
|
|
145
147
|
`loom db migrations setup-github`. Loom sends the value to GitHub over stdin,
|