@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.
Files changed (104) hide show
  1. package/README.md +108 -41
  2. package/esm/src/apiKeys/authorize.d.ts.map +1 -1
  3. package/esm/src/apiKeys/authorize.js +71 -0
  4. package/esm/src/apiKeys/betterAuth.d.ts +123 -0
  5. package/esm/src/apiKeys/betterAuth.d.ts.map +1 -0
  6. package/esm/src/apiKeys/betterAuth.js +164 -0
  7. package/esm/src/apiKeys/credentials.d.ts +37 -2
  8. package/esm/src/apiKeys/credentials.d.ts.map +1 -1
  9. package/esm/src/apiKeys/credentials.js +69 -8
  10. package/esm/src/apiKeys/lifecycle.d.ts +41 -0
  11. package/esm/src/apiKeys/lifecycle.d.ts.map +1 -0
  12. package/esm/src/apiKeys/lifecycle.js +6 -0
  13. package/esm/src/apiKeys/limits.d.ts +132 -0
  14. package/esm/src/apiKeys/limits.d.ts.map +1 -0
  15. package/esm/src/apiKeys/limits.js +246 -0
  16. package/esm/src/apiKeys/mod.d.ts +4 -0
  17. package/esm/src/apiKeys/mod.d.ts.map +1 -1
  18. package/esm/src/apiKeys/mod.js +4 -0
  19. package/esm/src/apiKeys/permissions.d.ts +56 -0
  20. package/esm/src/apiKeys/permissions.d.ts.map +1 -0
  21. package/esm/src/apiKeys/permissions.js +128 -0
  22. package/esm/src/apiKeys/policy.d.ts +3 -1
  23. package/esm/src/apiKeys/policy.d.ts.map +1 -1
  24. package/esm/src/apiKeys/policy.js +3 -1
  25. package/esm/src/apiKeys/types.d.ts +68 -1
  26. package/esm/src/apiKeys/types.d.ts.map +1 -1
  27. package/esm/src/cli/localDevLock.d.ts +97 -0
  28. package/esm/src/cli/localDevLock.d.ts.map +1 -0
  29. package/esm/src/cli/localDevLock.js +312 -0
  30. package/esm/src/cli/localDevPackage.d.ts +172 -0
  31. package/esm/src/cli/localDevPackage.d.ts.map +1 -0
  32. package/esm/src/cli/localDevPackage.js +617 -0
  33. package/esm/src/cli/migrationEnv.d.ts +19 -0
  34. package/esm/src/cli/migrationEnv.d.ts.map +1 -1
  35. package/esm/src/cli/migrationEnv.js +44 -1
  36. package/esm/src/cli/mod.d.ts +69 -4
  37. package/esm/src/cli/mod.d.ts.map +1 -1
  38. package/esm/src/cli/mod.js +2806 -437
  39. package/esm/src/cli/projectTooling.d.ts +19 -1
  40. package/esm/src/cli/projectTooling.d.ts.map +1 -1
  41. package/esm/src/cli/projectTooling.js +142 -12
  42. package/esm/src/mui/apiKeys.d.ts +123 -17
  43. package/esm/src/mui/apiKeys.d.ts.map +1 -1
  44. package/esm/src/mui/apiKeys.js +219 -78
  45. package/esm/src/mui/apiKeysView.d.ts +145 -0
  46. package/esm/src/mui/apiKeysView.d.ts.map +1 -1
  47. package/esm/src/mui/apiKeysView.js +278 -0
  48. package/esm/src/next/apiKeys/mod.d.ts +8 -1
  49. package/esm/src/next/apiKeys/mod.d.ts.map +1 -1
  50. package/esm/src/next/apiKeys/mod.js +5 -2
  51. package/package.json +2 -6
  52. package/script/src/apiKeys/authorize.d.ts.map +1 -1
  53. package/script/src/apiKeys/authorize.js +71 -0
  54. package/script/src/apiKeys/betterAuth.d.ts +123 -0
  55. package/script/src/apiKeys/betterAuth.d.ts.map +1 -0
  56. package/script/src/apiKeys/betterAuth.js +169 -0
  57. package/script/src/apiKeys/credentials.d.ts +37 -2
  58. package/script/src/apiKeys/credentials.d.ts.map +1 -1
  59. package/script/src/apiKeys/credentials.js +71 -8
  60. package/script/src/apiKeys/lifecycle.d.ts +41 -0
  61. package/script/src/apiKeys/lifecycle.d.ts.map +1 -0
  62. package/script/src/apiKeys/lifecycle.js +7 -0
  63. package/script/src/apiKeys/limits.d.ts +132 -0
  64. package/script/src/apiKeys/limits.d.ts.map +1 -0
  65. package/script/src/apiKeys/limits.js +254 -0
  66. package/script/src/apiKeys/mod.d.ts +4 -0
  67. package/script/src/apiKeys/mod.d.ts.map +1 -1
  68. package/script/src/apiKeys/mod.js +4 -0
  69. package/script/src/apiKeys/permissions.d.ts +56 -0
  70. package/script/src/apiKeys/permissions.d.ts.map +1 -0
  71. package/script/src/apiKeys/permissions.js +136 -0
  72. package/script/src/apiKeys/policy.d.ts +3 -1
  73. package/script/src/apiKeys/policy.d.ts.map +1 -1
  74. package/script/src/apiKeys/policy.js +3 -1
  75. package/script/src/apiKeys/types.d.ts +68 -1
  76. package/script/src/apiKeys/types.d.ts.map +1 -1
  77. package/script/src/cli/localDevLock.d.ts +97 -0
  78. package/script/src/cli/localDevLock.d.ts.map +1 -0
  79. package/script/src/cli/localDevLock.js +320 -0
  80. package/script/src/cli/localDevPackage.d.ts +172 -0
  81. package/script/src/cli/localDevPackage.d.ts.map +1 -0
  82. package/script/src/cli/localDevPackage.js +635 -0
  83. package/script/src/cli/migrationEnv.d.ts +19 -0
  84. package/script/src/cli/migrationEnv.d.ts.map +1 -1
  85. package/script/src/cli/migrationEnv.js +48 -1
  86. package/script/src/cli/mod.d.ts +69 -4
  87. package/script/src/cli/mod.d.ts.map +1 -1
  88. package/script/src/cli/mod.js +2807 -437
  89. package/script/src/cli/projectTooling.d.ts +19 -1
  90. package/script/src/cli/projectTooling.d.ts.map +1 -1
  91. package/script/src/cli/projectTooling.js +176 -12
  92. package/script/src/mui/apiKeys.d.ts +123 -17
  93. package/script/src/mui/apiKeys.d.ts.map +1 -1
  94. package/script/src/mui/apiKeys.js +220 -77
  95. package/script/src/mui/apiKeysView.d.ts +145 -0
  96. package/script/src/mui/apiKeysView.d.ts.map +1 -1
  97. package/script/src/mui/apiKeysView.js +291 -0
  98. package/script/src/next/apiKeys/mod.d.ts +8 -1
  99. package/script/src/next/apiKeys/mod.d.ts.map +1 -1
  100. package/script/src/next/apiKeys/mod.js +5 -2
  101. package/skills/loom/SKILL.md +111 -18
  102. package/skills/loom-api-keys/SKILL.md +101 -7
  103. package/skills/loom-auth/SKILL.md +9 -0
  104. 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 adapt `verifyApiKey()` exactly once.
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. Enable query transport
64
- only for routes whose consumer explicitly accepts URL-credential leakage, and
65
- keep audit metadata allowlisted and free of credential-bearing values.
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
@@ -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,