@gadicc/loom 0.0.0-oidc-bootstrap.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/LICENSE +201 -0
- package/NOTICE +6 -0
- package/README.md +448 -0
- package/THIRD_PARTY_NOTICES.md +25 -0
- package/db/drizzle-config.d.ts +20 -0
- package/db/drizzle-config.js +34 -0
- package/db/fixtures.d.ts +31 -0
- package/db/fixtures.js +52 -0
- package/db/neon.d.ts +3 -0
- package/db/neon.js +20 -0
- package/db/neonFull.d.ts +12 -0
- package/db/neonFull.js +33 -0
- package/db/package.json +3 -0
- package/db/testing.d.ts +26 -0
- package/db/testing.js +76 -0
- package/db/testing.test.ts +28 -0
- package/db/valibot.d.ts +23 -0
- package/db/valibot.js +8 -0
- package/esm/_dnt.polyfills.d.ts +149 -0
- package/esm/_dnt.polyfills.d.ts.map +1 -0
- package/esm/_dnt.polyfills.js +163 -0
- package/esm/_dnt.shims.d.ts +2 -0
- package/esm/_dnt.shims.d.ts.map +1 -0
- package/esm/_dnt.shims.js +57 -0
- package/esm/bin/loom.d.ts +2 -0
- package/esm/bin/loom.d.ts.map +1 -0
- package/esm/bin/loom.js +11 -0
- package/esm/mod.d.ts +9 -0
- package/esm/mod.d.ts.map +1 -0
- package/esm/mod.js +8 -0
- package/esm/package.json +3 -0
- package/esm/src/apiKeys/authorize.d.ts +4 -0
- package/esm/src/apiKeys/authorize.d.ts.map +1 -0
- package/esm/src/apiKeys/authorize.js +184 -0
- package/esm/src/apiKeys/country.d.ts +3 -0
- package/esm/src/apiKeys/country.d.ts.map +1 -0
- package/esm/src/apiKeys/country.js +7 -0
- package/esm/src/apiKeys/credentials.d.ts +4 -0
- package/esm/src/apiKeys/credentials.d.ts.map +1 -0
- package/esm/src/apiKeys/credentials.js +55 -0
- package/esm/src/apiKeys/fingerprint.d.ts +3 -0
- package/esm/src/apiKeys/fingerprint.d.ts.map +1 -0
- package/esm/src/apiKeys/fingerprint.js +5 -0
- package/esm/src/apiKeys/mod.d.ts +9 -0
- package/esm/src/apiKeys/mod.d.ts.map +1 -0
- package/esm/src/apiKeys/mod.js +8 -0
- package/esm/src/apiKeys/policy.d.ts +59 -0
- package/esm/src/apiKeys/policy.d.ts.map +1 -0
- package/esm/src/apiKeys/policy.js +88 -0
- package/esm/src/apiKeys/retention.d.ts +55 -0
- package/esm/src/apiKeys/retention.d.ts.map +1 -0
- package/esm/src/apiKeys/retention.js +65 -0
- package/esm/src/apiKeys/types.d.ts +175 -0
- package/esm/src/apiKeys/types.d.ts.map +1 -0
- package/esm/src/apiKeys/types.js +1 -0
- package/esm/src/cli/externalSkills.d.ts +39 -0
- package/esm/src/cli/externalSkills.d.ts.map +1 -0
- package/esm/src/cli/externalSkills.js +177 -0
- package/esm/src/cli/mod.d.ts +337 -0
- package/esm/src/cli/mod.d.ts.map +1 -0
- package/esm/src/cli/mod.js +9268 -0
- package/esm/src/cli/projectSkills.d.ts +102 -0
- package/esm/src/cli/projectSkills.d.ts.map +1 -0
- package/esm/src/cli/projectSkills.js +592 -0
- package/esm/src/files/client.d.ts +29 -0
- package/esm/src/files/client.d.ts.map +1 -0
- package/esm/src/files/client.js +41 -0
- package/esm/src/files/errors.d.ts +37 -0
- package/esm/src/files/errors.d.ts.map +1 -0
- package/esm/src/files/errors.js +66 -0
- package/esm/src/files/hash.d.ts +15 -0
- package/esm/src/files/hash.d.ts.map +1 -0
- package/esm/src/files/hash.js +82 -0
- package/esm/src/files/memory.d.ts +29 -0
- package/esm/src/files/memory.d.ts.map +1 -0
- package/esm/src/files/memory.js +109 -0
- package/esm/src/files/metadata.d.ts +10 -0
- package/esm/src/files/metadata.d.ts.map +1 -0
- package/esm/src/files/metadata.js +186 -0
- package/esm/src/files/mod.d.ts +10 -0
- package/esm/src/files/mod.d.ts.map +1 -0
- package/esm/src/files/mod.js +9 -0
- package/esm/src/files/s3.d.ts +29 -0
- package/esm/src/files/s3.d.ts.map +1 -0
- package/esm/src/files/s3.js +107 -0
- package/esm/src/files/service.d.ts +27 -0
- package/esm/src/files/service.d.ts.map +1 -0
- package/esm/src/files/service.js +136 -0
- package/esm/src/files/types.d.ts +134 -0
- package/esm/src/files/types.d.ts.map +1 -0
- package/esm/src/files/types.js +1 -0
- package/esm/src/jobs/catalog.d.ts +32 -0
- package/esm/src/jobs/catalog.d.ts.map +1 -0
- package/esm/src/jobs/catalog.js +208 -0
- package/esm/src/jobs/controller.d.ts +28 -0
- package/esm/src/jobs/controller.d.ts.map +1 -0
- package/esm/src/jobs/controller.js +95 -0
- package/esm/src/jobs/direct.d.ts +36 -0
- package/esm/src/jobs/direct.d.ts.map +1 -0
- package/esm/src/jobs/direct.js +122 -0
- package/esm/src/jobs/events.d.ts +15 -0
- package/esm/src/jobs/events.d.ts.map +1 -0
- package/esm/src/jobs/events.js +30 -0
- package/esm/src/jobs/format.d.ts +16 -0
- package/esm/src/jobs/format.d.ts.map +1 -0
- package/esm/src/jobs/format.js +183 -0
- package/esm/src/jobs/http.d.ts +22 -0
- package/esm/src/jobs/http.d.ts.map +1 -0
- package/esm/src/jobs/http.js +44 -0
- package/esm/src/jobs/log.d.ts +2 -0
- package/esm/src/jobs/log.d.ts.map +1 -0
- package/esm/src/jobs/log.js +10 -0
- package/esm/src/jobs/mod.d.ts +10 -0
- package/esm/src/jobs/mod.d.ts.map +1 -0
- package/esm/src/jobs/mod.js +9 -0
- package/esm/src/jobs/run.d.ts +20 -0
- package/esm/src/jobs/run.d.ts.map +1 -0
- package/esm/src/jobs/run.js +57 -0
- package/esm/src/jobs/types.d.ts +31 -0
- package/esm/src/jobs/types.d.ts.map +1 -0
- package/esm/src/jobs/types.js +1 -0
- package/esm/src/mui/apiKeys.d.ts +65 -0
- package/esm/src/mui/apiKeys.d.ts.map +1 -0
- package/esm/src/mui/apiKeys.js +301 -0
- package/esm/src/mui/apiKeysView.d.ts +48 -0
- package/esm/src/mui/apiKeysView.d.ts.map +1 -0
- package/esm/src/mui/apiKeysView.js +34 -0
- package/esm/src/mui/confirm.d.ts +12 -0
- package/esm/src/mui/confirm.d.ts.map +1 -0
- package/esm/src/mui/confirm.js +78 -0
- package/esm/src/mui/mod.d.ts +4 -0
- package/esm/src/mui/mod.d.ts.map +1 -0
- package/esm/src/mui/mod.js +2 -0
- package/esm/src/next/apiKeys/mod.d.ts +64 -0
- package/esm/src/next/apiKeys/mod.d.ts.map +1 -0
- package/esm/src/next/apiKeys/mod.js +217 -0
- package/esm/src/next/auth/config.d.ts +34 -0
- package/esm/src/next/auth/config.d.ts.map +1 -0
- package/esm/src/next/auth/config.js +103 -0
- package/esm/src/next/auth/mod.d.ts +3 -0
- package/esm/src/next/auth/mod.d.ts.map +1 -0
- package/esm/src/next/auth/mod.js +2 -0
- package/esm/src/next/auth/server.d.ts +28 -0
- package/esm/src/next/auth/server.d.ts.map +1 -0
- package/esm/src/next/auth/server.js +24 -0
- package/esm/src/next/files/mod.d.ts +3 -0
- package/esm/src/next/files/mod.d.ts.map +1 -0
- package/esm/src/next/files/mod.js +2 -0
- package/esm/src/next/files/route.d.ts +99 -0
- package/esm/src/next/files/route.d.ts.map +1 -0
- package/esm/src/next/files/route.js +349 -0
- package/esm/src/next/jobs/list.d.ts +25 -0
- package/esm/src/next/jobs/list.d.ts.map +1 -0
- package/esm/src/next/jobs/list.js +39 -0
- package/esm/src/next/jobs/mod.d.ts +6 -0
- package/esm/src/next/jobs/mod.d.ts.map +1 -0
- package/esm/src/next/jobs/mod.js +5 -0
- package/esm/src/next/jobs/paths.d.ts +14 -0
- package/esm/src/next/jobs/paths.d.ts.map +1 -0
- package/esm/src/next/jobs/paths.js +40 -0
- package/esm/src/next/jobs/route.d.ts +48 -0
- package/esm/src/next/jobs/route.d.ts.map +1 -0
- package/esm/src/next/jobs/route.js +101 -0
- package/esm/src/next/jobs/run.d.ts +51 -0
- package/esm/src/next/jobs/run.d.ts.map +1 -0
- package/esm/src/next/jobs/run.js +563 -0
- package/esm/src/next/jobs/stream.d.ts +3 -0
- package/esm/src/next/jobs/stream.d.ts.map +1 -0
- package/esm/src/next/jobs/stream.js +25 -0
- package/esm/src/next/pwa/mod.d.ts +104 -0
- package/esm/src/next/pwa/mod.d.ts.map +1 -0
- package/esm/src/next/pwa/mod.js +169 -0
- package/esm/src/next/pwa/worker.d.ts +27 -0
- package/esm/src/next/pwa/worker.d.ts.map +1 -0
- package/esm/src/next/pwa/worker.js +27 -0
- package/package.json +293 -0
- package/script/_dnt.polyfills.d.ts +149 -0
- package/script/_dnt.polyfills.d.ts.map +1 -0
- package/script/_dnt.polyfills.js +166 -0
- package/script/_dnt.shims.d.ts +2 -0
- package/script/_dnt.shims.d.ts.map +1 -0
- package/script/_dnt.shims.js +60 -0
- package/script/bin/loom.d.ts +2 -0
- package/script/bin/loom.d.ts.map +1 -0
- package/script/bin/loom.js +17 -0
- package/script/mod.d.ts +9 -0
- package/script/mod.d.ts.map +1 -0
- package/script/mod.js +24 -0
- package/script/package.json +3 -0
- package/script/src/apiKeys/authorize.d.ts +4 -0
- package/script/src/apiKeys/authorize.d.ts.map +1 -0
- package/script/src/apiKeys/authorize.js +187 -0
- package/script/src/apiKeys/country.d.ts +3 -0
- package/script/src/apiKeys/country.d.ts.map +1 -0
- package/script/src/apiKeys/country.js +10 -0
- package/script/src/apiKeys/credentials.d.ts +4 -0
- package/script/src/apiKeys/credentials.d.ts.map +1 -0
- package/script/src/apiKeys/credentials.js +58 -0
- package/script/src/apiKeys/fingerprint.d.ts +3 -0
- package/script/src/apiKeys/fingerprint.d.ts.map +1 -0
- package/script/src/apiKeys/fingerprint.js +8 -0
- package/script/src/apiKeys/mod.d.ts +9 -0
- package/script/src/apiKeys/mod.d.ts.map +1 -0
- package/script/src/apiKeys/mod.js +24 -0
- package/script/src/apiKeys/policy.d.ts +59 -0
- package/script/src/apiKeys/policy.d.ts.map +1 -0
- package/script/src/apiKeys/policy.js +92 -0
- package/script/src/apiKeys/retention.d.ts +55 -0
- package/script/src/apiKeys/retention.d.ts.map +1 -0
- package/script/src/apiKeys/retention.js +70 -0
- package/script/src/apiKeys/types.d.ts +175 -0
- package/script/src/apiKeys/types.d.ts.map +1 -0
- package/script/src/apiKeys/types.js +2 -0
- package/script/src/cli/externalSkills.d.ts +39 -0
- package/script/src/cli/externalSkills.d.ts.map +1 -0
- package/script/src/cli/externalSkills.js +181 -0
- package/script/src/cli/mod.d.ts +337 -0
- package/script/src/cli/mod.d.ts.map +1 -0
- package/script/src/cli/mod.js +9337 -0
- package/script/src/cli/projectSkills.d.ts +102 -0
- package/script/src/cli/projectSkills.d.ts.map +1 -0
- package/script/src/cli/projectSkills.js +606 -0
- package/script/src/files/client.d.ts +29 -0
- package/script/src/files/client.d.ts.map +1 -0
- package/script/src/files/client.js +45 -0
- package/script/src/files/errors.d.ts +37 -0
- package/script/src/files/errors.d.ts.map +1 -0
- package/script/src/files/errors.js +76 -0
- package/script/src/files/hash.d.ts +15 -0
- package/script/src/files/hash.d.ts.map +1 -0
- package/script/src/files/hash.js +89 -0
- package/script/src/files/memory.d.ts +29 -0
- package/script/src/files/memory.d.ts.map +1 -0
- package/script/src/files/memory.js +113 -0
- package/script/src/files/metadata.d.ts +10 -0
- package/script/src/files/metadata.d.ts.map +1 -0
- package/script/src/files/metadata.js +189 -0
- package/script/src/files/mod.d.ts +10 -0
- package/script/src/files/mod.d.ts.map +1 -0
- package/script/src/files/mod.js +25 -0
- package/script/src/files/s3.d.ts +29 -0
- package/script/src/files/s3.d.ts.map +1 -0
- package/script/src/files/s3.js +110 -0
- package/script/src/files/service.d.ts +27 -0
- package/script/src/files/service.d.ts.map +1 -0
- package/script/src/files/service.js +139 -0
- package/script/src/files/types.d.ts +134 -0
- package/script/src/files/types.d.ts.map +1 -0
- package/script/src/files/types.js +2 -0
- package/script/src/jobs/catalog.d.ts +32 -0
- package/script/src/jobs/catalog.d.ts.map +1 -0
- package/script/src/jobs/catalog.js +223 -0
- package/script/src/jobs/controller.d.ts +28 -0
- package/script/src/jobs/controller.d.ts.map +1 -0
- package/script/src/jobs/controller.js +100 -0
- package/script/src/jobs/direct.d.ts +36 -0
- package/script/src/jobs/direct.d.ts.map +1 -0
- package/script/src/jobs/direct.js +128 -0
- package/script/src/jobs/events.d.ts +15 -0
- package/script/src/jobs/events.d.ts.map +1 -0
- package/script/src/jobs/events.js +37 -0
- package/script/src/jobs/format.d.ts +16 -0
- package/script/src/jobs/format.d.ts.map +1 -0
- package/script/src/jobs/format.js +193 -0
- package/script/src/jobs/http.d.ts +22 -0
- package/script/src/jobs/http.d.ts.map +1 -0
- package/script/src/jobs/http.js +50 -0
- package/script/src/jobs/log.d.ts +2 -0
- package/script/src/jobs/log.d.ts.map +1 -0
- package/script/src/jobs/log.js +13 -0
- package/script/src/jobs/mod.d.ts +10 -0
- package/script/src/jobs/mod.d.ts.map +1 -0
- package/script/src/jobs/mod.js +25 -0
- package/script/src/jobs/run.d.ts +20 -0
- package/script/src/jobs/run.d.ts.map +1 -0
- package/script/src/jobs/run.js +61 -0
- package/script/src/jobs/types.d.ts +31 -0
- package/script/src/jobs/types.d.ts.map +1 -0
- package/script/src/jobs/types.js +2 -0
- package/script/src/mui/apiKeys.d.ts +65 -0
- package/script/src/mui/apiKeys.d.ts.map +1 -0
- package/script/src/mui/apiKeys.js +327 -0
- package/script/src/mui/apiKeysView.d.ts +48 -0
- package/script/src/mui/apiKeysView.d.ts.map +1 -0
- package/script/src/mui/apiKeysView.js +40 -0
- package/script/src/mui/confirm.d.ts +12 -0
- package/script/src/mui/confirm.d.ts.map +1 -0
- package/script/src/mui/confirm.js +85 -0
- package/script/src/mui/mod.d.ts +4 -0
- package/script/src/mui/mod.d.ts.map +1 -0
- package/script/src/mui/mod.js +19 -0
- package/script/src/next/apiKeys/mod.d.ts +64 -0
- package/script/src/next/apiKeys/mod.d.ts.map +1 -0
- package/script/src/next/apiKeys/mod.js +224 -0
- package/script/src/next/auth/config.d.ts +34 -0
- package/script/src/next/auth/config.d.ts.map +1 -0
- package/script/src/next/auth/config.js +142 -0
- package/script/src/next/auth/mod.d.ts +3 -0
- package/script/src/next/auth/mod.d.ts.map +1 -0
- package/script/src/next/auth/mod.js +18 -0
- package/script/src/next/auth/server.d.ts +28 -0
- package/script/src/next/auth/server.d.ts.map +1 -0
- package/script/src/next/auth/server.js +27 -0
- package/script/src/next/files/mod.d.ts +3 -0
- package/script/src/next/files/mod.d.ts.map +1 -0
- package/script/src/next/files/mod.js +18 -0
- package/script/src/next/files/route.d.ts +99 -0
- package/script/src/next/files/route.d.ts.map +1 -0
- package/script/src/next/files/route.js +353 -0
- package/script/src/next/jobs/list.d.ts +25 -0
- package/script/src/next/jobs/list.d.ts.map +1 -0
- package/script/src/next/jobs/list.js +48 -0
- package/script/src/next/jobs/mod.d.ts +6 -0
- package/script/src/next/jobs/mod.d.ts.map +1 -0
- package/script/src/next/jobs/mod.js +21 -0
- package/script/src/next/jobs/paths.d.ts +14 -0
- package/script/src/next/jobs/paths.d.ts.map +1 -0
- package/script/src/next/jobs/paths.js +47 -0
- package/script/src/next/jobs/route.d.ts +48 -0
- package/script/src/next/jobs/route.d.ts.map +1 -0
- package/script/src/next/jobs/route.js +105 -0
- package/script/src/next/jobs/run.d.ts +51 -0
- package/script/src/next/jobs/run.d.ts.map +1 -0
- package/script/src/next/jobs/run.js +570 -0
- package/script/src/next/jobs/stream.d.ts +3 -0
- package/script/src/next/jobs/stream.d.ts.map +1 -0
- package/script/src/next/jobs/stream.js +28 -0
- package/script/src/next/pwa/mod.d.ts +104 -0
- package/script/src/next/pwa/mod.d.ts.map +1 -0
- package/script/src/next/pwa/mod.js +192 -0
- package/script/src/next/pwa/worker.d.ts +27 -0
- package/script/src/next/pwa/worker.d.ts.map +1 -0
- package/script/src/next/pwa/worker.js +33 -0
- package/skills/loom/SKILL.md +200 -0
- package/skills/loom-api-keys/SKILL.md +123 -0
- package/skills/loom-auth/SKILL.md +70 -0
- package/skills/loom-db/SKILL.md +94 -0
- package/skills/loom-db/references/db-stack.md +39 -0
- package/skills/loom-files/SKILL.md +97 -0
- package/skills/loom-jobs/SKILL.md +148 -0
- package/skills/upgrade-deps/SKILL.md +165 -0
- package/skills/upgrade-deps/agents/openai.yaml +4 -0
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: loom-api-keys
|
|
3
|
+
description: Use when adopting Loom API keys, the managed audit schema, API-key route authorization, Vercel IP/country snapshots, key management UI, audit retention, or explicit jobs integration.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Loom API keys
|
|
7
|
+
|
|
8
|
+
Read `loom.json`, then inspect `features.api-keys.config`. Better Auth remains
|
|
9
|
+
the authority for key creation, hashing, enablement, expiry, and native
|
|
10
|
+
permissions. The app owns its Better Auth plugin configuration, verifier,
|
|
11
|
+
current-role policy, audit repository, lifecycle actions, and migrations.
|
|
12
|
+
|
|
13
|
+
## Foundation and integrations
|
|
14
|
+
|
|
15
|
+
- `loom add api-keys` requires active `auth` and `db`, materializes the
|
|
16
|
+
hash-tracked audit schema, and scaffolds safe stubs. It never creates SQL.
|
|
17
|
+
- Replace the deny-all policy, verifier, audit repository, and lifecycle action
|
|
18
|
+
stubs before production.
|
|
19
|
+
- Install compatible matching `better-auth` and `@better-auth/api-key` versions.
|
|
20
|
+
Keep API-key sessions disabled and adapt `verifyApiKey()` exactly once.
|
|
21
|
+
- Foundation installation does not authorize any existing HTTP surface.
|
|
22
|
+
- Enable jobs separately with
|
|
23
|
+
`loom api-keys integrate jobs --resource jobs --action execute`. The command
|
|
24
|
+
refuses an unguarded jobs HTTP route and never replaces browser/session auth.
|
|
25
|
+
- Direct local job runners import the catalog and execute in the trusted local
|
|
26
|
+
process. They remain API-key-free. A future remote HTTP client is a different
|
|
27
|
+
trust boundary and must authenticate.
|
|
28
|
+
|
|
29
|
+
## Adoption checklist
|
|
30
|
+
|
|
31
|
+
- Activate `auth`, `db`, then `api-keys`; review the managed schema and generate
|
|
32
|
+
the consumer migration deliberately. Existing installs sync to audit blueprint
|
|
33
|
+
v3 before migration generation.
|
|
34
|
+
- Replace all generated safe stubs. Implement the verifier exactly once, fresh
|
|
35
|
+
role/owner policy, audit append/list and retention repositories, and
|
|
36
|
+
owner/admin lifecycle actions.
|
|
37
|
+
- On directly hosted Vercel routes, add
|
|
38
|
+
`requestContext: vercelApiKeyRequestContext`. Supply deterministic context in
|
|
39
|
+
local tests because Vercel geolocation headers are deployment-only.
|
|
40
|
+
- Derive recent use from the newest allowed authorization event, not Better
|
|
41
|
+
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
|
+
- Exercise denial, audit-outage, handler-failure, query-credential, and stream
|
|
44
|
+
behavior before enabling a route. Run `loom check` and app checks afterward.
|
|
45
|
+
|
|
46
|
+
## Adding consumer scopes
|
|
47
|
+
|
|
48
|
+
- Keep the shared Loom layer scope-agnostic. Define consumer permissions with
|
|
49
|
+
`defineApiKeyScopes` using stable resource/action names, and treat names
|
|
50
|
+
already issued to keys as a compatibility contract. Use its `list` projection
|
|
51
|
+
for UI and its `permissions` projection for route descriptors.
|
|
52
|
+
- Build the consumer's server policy with `createApiKeyPolicy`. Every registered
|
|
53
|
+
scope must have an explicit `"allow"`, `"deny"`, or callback rule; unknown
|
|
54
|
+
resource/action pairs deny automatically. Enforce creation-time eligibility
|
|
55
|
+
separately, and use callbacks to re-check mutable privileges such as current
|
|
56
|
+
roles at use time.
|
|
57
|
+
- Give each protected operation a stable audit operation name and the exact
|
|
58
|
+
required permission in its route descriptor. Foundation installation or a
|
|
59
|
+
registry entry alone must never expose an HTTP capability.
|
|
60
|
+
- Carry the verified principal into the handler and constrain user-owned data in
|
|
61
|
+
its database query. Do not fetch broadly and filter afterward; define global
|
|
62
|
+
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.
|
|
66
|
+
- Do not silently expand existing keys when a scope is introduced. Require a
|
|
67
|
+
replacement key for increased authority.
|
|
68
|
+
- A new native resource/action value normally uses the existing Better Auth
|
|
69
|
+
permission field and Loom text audit columns, so it does not by itself require
|
|
70
|
+
a migration. Generate one only when the consumer's persistence shape changes.
|
|
71
|
+
- Test registry conversion and forged IDs, creation and fresh use-time policy,
|
|
72
|
+
wrong-scope and revoked keys, configured transports and ambiguity rejection,
|
|
73
|
+
database ownership, and audit failure before handler execution.
|
|
74
|
+
- Add a shared integration hook and manifest contract only when the capability
|
|
75
|
+
is reusable across consumers. App-specific routes should use the generic
|
|
76
|
+
authorization wrapper and remain in the consumer.
|
|
77
|
+
|
|
78
|
+
## Security boundaries
|
|
79
|
+
|
|
80
|
+
- Bearer and `X-API-Key` are enabled by default. Query credentials require an
|
|
81
|
+
explicit consumer opt-in and can leak through browser history, access logs,
|
|
82
|
+
copied links, and referrers.
|
|
83
|
+
- Reject multiple transports even when values match.
|
|
84
|
+
- Never log or persist plaintext keys, authorization headers, full URLs, query
|
|
85
|
+
strings, or arbitrary handler parameters.
|
|
86
|
+
- An allowed authorization audit event must be durable before execution. Denied
|
|
87
|
+
requests remain denied if denial auditing is unavailable.
|
|
88
|
+
- Completion events describe response creation for streaming responses; Loom
|
|
89
|
+
does not buffer streams to observe full consumption.
|
|
90
|
+
- On Vercel, prefer `vercelApiKeyRequestContext` to snapshot the platform-owned
|
|
91
|
+
IP and country headers with no lookup dependency. The headers are absent
|
|
92
|
+
locally and require special handling when another proxy fronts Vercel.
|
|
93
|
+
- Elsewhere, resolve an optional country code from the app's trusted originating
|
|
94
|
+
IP with `resolveCountryCode`. Prefer an offline, build-refreshed database such
|
|
95
|
+
as `ip-location-api/pack` with `user-country`; never make a request-time
|
|
96
|
+
geolocation service call. Resolver failures must not affect auth.
|
|
97
|
+
- Persist the ISO country code with the authorization event and render that
|
|
98
|
+
snapshot. Do not re-resolve historical audit rows after database updates.
|
|
99
|
+
- Revoke by disabling keys so audit attribution and snapshots remain intact.
|
|
100
|
+
|
|
101
|
+
## Audit retention
|
|
102
|
+
|
|
103
|
+
- The general default is 180 days, 5,000 authorization request groups per key,
|
|
104
|
+
and batches of 1,000 request groups. Do not count physical rows: delete an
|
|
105
|
+
authorization event and its completion event atomically.
|
|
106
|
+
- Run `loom api-keys retention enable` to record an explicit policy. It does not
|
|
107
|
+
modify jobs or create a schedule.
|
|
108
|
+
- Implement `apiKeyAuditRetentionRepository.pruneBatch` against the
|
|
109
|
+
`ApiKeyAuditRetentionRepository` contract and schedule
|
|
110
|
+
`runApiKeyAuditRetention` daily in app-owned infrastructure.
|
|
111
|
+
- Prefer a trusted in-process scheduler invocation. If cleanup is exposed over
|
|
112
|
+
HTTP, require explicit scheduler authentication; never create a public
|
|
113
|
+
maintenance route.
|
|
114
|
+
- Apply the age cutoff to unattributed denials. Apply the per-key cap only where
|
|
115
|
+
a key is attributed, retaining the newest request groups.
|
|
116
|
+
- Monitor `complete`; retry or alert when the runner reaches its batch safety
|
|
117
|
+
bound. Record aggregate cleanup metrics outside the audit table.
|
|
118
|
+
- Override retention for documented legal, regulatory, contractual, incident, or
|
|
119
|
+
legal-hold needs. PCI-scoped consumers commonly need at least 365 days.
|
|
120
|
+
|
|
121
|
+
Run `loom check` during development and `loom check --production` before
|
|
122
|
+
release. After a schema materialization or sync, review the diff and generate
|
|
123
|
+
the app-local migration deliberately.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: loom-auth
|
|
3
|
+
description: Use when a Loom consumer changes Better Auth wiring, BETTER_AUTH_SECRET or BETTER_AUTH_SECRETS, auth cookie/session settings, or environment-specific auth configuration.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Loom Auth
|
|
7
|
+
|
|
8
|
+
Use this skill for the shared Better Auth boundary in a consuming app.
|
|
9
|
+
|
|
10
|
+
## Start here
|
|
11
|
+
|
|
12
|
+
1. Read `loom.json` and use the configured auth module and route paths.
|
|
13
|
+
2. Check the installed `better-auth` version before recommending versioned
|
|
14
|
+
secret rotation. `BETTER_AUTH_SECRETS` requires Better Auth 1.5 or newer.
|
|
15
|
+
3. Keep database adapters, providers, plugins, redirect behavior, and app-local
|
|
16
|
+
session enrichment in the consumer.
|
|
17
|
+
|
|
18
|
+
## Secret loading
|
|
19
|
+
|
|
20
|
+
- Keep `requireBetterAuthSecret()` in the module-level `betterAuth()` config.
|
|
21
|
+
Failing during module initialization catches missing production config during
|
|
22
|
+
a build instead of allowing an insecure runtime default.
|
|
23
|
+
- When `BETTER_AUTH_SECRETS` exists, Better Auth reads the complete versioned
|
|
24
|
+
list directly. The helper validates that list and returns `BETTER_AUTH_SECRET`
|
|
25
|
+
as Better Auth's legacy fallback when it exists; do not parse the first
|
|
26
|
+
version into a replacement singular environment variable.
|
|
27
|
+
- Do not use a dummy build secret for a production artifact. Vercel's
|
|
28
|
+
`vercel pull` build path can provide Sensitive variables to an external CI
|
|
29
|
+
runner, and server-only variables are read again in the deployed runtime.
|
|
30
|
+
- Treat `.vercel/.env.<target>.local` as a plaintext secret file. Keep it
|
|
31
|
+
ignored, mask pulled values in GitHub Actions before later commands can log
|
|
32
|
+
them, and do not cache or upload it as an artifact.
|
|
33
|
+
- `vercel env run` does not provide Sensitive variables. CI commands that need
|
|
34
|
+
the production secret set should run from the file created by `vercel pull`.
|
|
35
|
+
|
|
36
|
+
## Rotation
|
|
37
|
+
|
|
38
|
+
- Prefer Better Auth's versioned rotation with
|
|
39
|
+
`BETTER_AUTH_SECRETS=2:new,1:old`; the first entry signs new data and older
|
|
40
|
+
entries remain available for decryption.
|
|
41
|
+
- Preserve `BETTER_AUTH_SECRET` during the first versioned rollout when legacy
|
|
42
|
+
data predates the versioned envelope. Better Auth uses the singular value as
|
|
43
|
+
that legacy fallback.
|
|
44
|
+
- Sensitive Vercel variables are intentionally unreadable after creation. Store
|
|
45
|
+
recovery and previous rotation values in the team's password manager before
|
|
46
|
+
converting or replacing them.
|
|
47
|
+
- Do not delete an old key until the app's longest relevant session, cookie,
|
|
48
|
+
verification, and token lifetime has elapsed and active OAuth flows have had
|
|
49
|
+
time to finish.
|
|
50
|
+
|
|
51
|
+
## Production and Preview
|
|
52
|
+
|
|
53
|
+
Use different auth signing keys when Preview is a different trust boundary.
|
|
54
|
+
Sharing a key is more than a logging-isolation concern: preview code that gains
|
|
55
|
+
the key can sign or decrypt data accepted by Production when cookie names,
|
|
56
|
+
domains, or backing data overlap. Separate host-only cookies and isolated
|
|
57
|
+
Preview databases reduce the practical risk, so this is guidance rather than a
|
|
58
|
+
blanket release blocker for trusted long-lived previews.
|
|
59
|
+
|
|
60
|
+
If the app uses Better Auth's OAuth Proxy plugin, check that plugin's secret
|
|
61
|
+
requirements before separating keys; the proxy may need an explicitly shared
|
|
62
|
+
secret for cross-environment state exchange.
|
|
63
|
+
|
|
64
|
+
## Verification
|
|
65
|
+
|
|
66
|
+
- Run `loom check` and the consumer's typecheck/tests.
|
|
67
|
+
- Run a production Vercel build after changing secret selection or auth module
|
|
68
|
+
initialization.
|
|
69
|
+
- Confirm server-only secret values do not occur in `.next/static`, generated
|
|
70
|
+
client chunks, cached artifacts, or committed files.
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: loom-db
|
|
3
|
+
description: Use when the task mentions the loom db feature, neon.ts, neonFull.ts, drizzle.config.ts, loom db schema-gen, valibot-generated schemas, PGlite DB tests, or repairing loom-managed DB wrappers and scripts in a consuming app.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Loom DB
|
|
7
|
+
|
|
8
|
+
Use this skill when working on the shared DB stack from a consuming app.
|
|
9
|
+
|
|
10
|
+
## Start here
|
|
11
|
+
|
|
12
|
+
1. Read `loom.json`.
|
|
13
|
+
2. Inspect `features.db.config` and use the configured module and directory
|
|
14
|
+
paths instead of assuming defaults.
|
|
15
|
+
3. Check the app-local schema barrel before changing any Loom-managed DB files.
|
|
16
|
+
|
|
17
|
+
## Ownership boundaries
|
|
18
|
+
|
|
19
|
+
- App-local Drizzle schemas remain the source of truth.
|
|
20
|
+
- Loom schema blueprints may be materialized into committed app-local schema
|
|
21
|
+
files for schema-bearing features such as `files`; migrations remain app-local
|
|
22
|
+
and explicit.
|
|
23
|
+
- Loom owns the standard wiring around thin wrappers for `neon.ts`,
|
|
24
|
+
`neonFull.ts`, `drizzle.config.ts`, `schema:gen`, `db:fixtures`, and the
|
|
25
|
+
shared PGlite test harness.
|
|
26
|
+
- Valibot generated files stay app-local, but should be regenerated through
|
|
27
|
+
`loom db schema-gen` instead of ad hoc commands.
|
|
28
|
+
- DB-backed scripts, Drizzle commands, direct SQL inspection, and migrations
|
|
29
|
+
should use the app's env-aware package scripts or
|
|
30
|
+
`pnpm exec loom env -- <command>`. Do not add `dotenv` or `@next/env` imports
|
|
31
|
+
to implementation files.
|
|
32
|
+
- `createDrizzleConfig()` prefers `DATABASE_URL_UNPOOLED` when Vercel/Neon
|
|
33
|
+
provides it and falls back to `DATABASE_URL`, so local environments do not
|
|
34
|
+
need to define both.
|
|
35
|
+
- App-specific fixture table selection, extra Valibot refinements, and auth
|
|
36
|
+
integration should stay local unless they are being extracted deliberately.
|
|
37
|
+
|
|
38
|
+
## What to preserve
|
|
39
|
+
|
|
40
|
+
- Existing local schema files and migrations.
|
|
41
|
+
- Managed schema blueprint files whose current hash matches `loom.json`; put
|
|
42
|
+
app-specific schema changes in separate local schema files instead of editing
|
|
43
|
+
generated blueprint files.
|
|
44
|
+
- Intentional refinements under `src/db/valibot/refinements`.
|
|
45
|
+
- Any app-local fixture filtering logic inside `scripts/dump-test-tables.ts`.
|
|
46
|
+
- Transactional code paths that depend on `neonFull.ts`.
|
|
47
|
+
|
|
48
|
+
## Validation and tests
|
|
49
|
+
|
|
50
|
+
- Use `loom db schema-gen` after schema changes that affect generated Valibot
|
|
51
|
+
output.
|
|
52
|
+
- Use `loom db schemas sync` to refresh active Loom-managed schema blueprints,
|
|
53
|
+
then review diffs and run the normal migration generation flow deliberately.
|
|
54
|
+
- Keep `src/db/valibot/generated/*` generated and committed, never hand-edited.
|
|
55
|
+
- Prefer `tests/memory-pglite.ts` plus a mock of `@/db/neon` or `@/db/neonFull`
|
|
56
|
+
for DB-backed unit tests.
|
|
57
|
+
- If fixtures are used, keep them under `tests/fixtures/db/` and serialize them
|
|
58
|
+
with `superjson`.
|
|
59
|
+
|
|
60
|
+
## Verification
|
|
61
|
+
|
|
62
|
+
- Run `loom check` after DB feature changes.
|
|
63
|
+
- Confirm package scripts still point at Loom-managed commands, especially
|
|
64
|
+
`schema:gen`, `db:fixtures`, and the Drizzle script that runs through
|
|
65
|
+
`loom env --`.
|
|
66
|
+
- Confirm `drizzle.config.ts` still points at the configured schema and drizzle
|
|
67
|
+
directories.
|
|
68
|
+
- Confirm the Valibot barrel matches the generated and refinement modules.
|
|
69
|
+
- Confirm active Loom-managed feature schemas match their recorded hash in
|
|
70
|
+
`loom.json` and are exported from the app-local schema barrel.
|
|
71
|
+
- For Vercel production releases, confirm `vercel.json` disables automatic
|
|
72
|
+
`main` deployments and GitHub Actions builds with Vercel production settings,
|
|
73
|
+
uploads a staged production deployment with `--prebuilt --prod --skip-domain`,
|
|
74
|
+
runs `db:migrate` with the env file produced by `vercel pull`, and then
|
|
75
|
+
promotes the staged deployment. `vercel env run` omits Sensitive variables and
|
|
76
|
+
is not the release migration boundary. Pass `--scope "$VERCEL_ORG_ID"` to
|
|
77
|
+
Vercel CLI release commands so multi-account CI jobs do not resolve the wrong
|
|
78
|
+
team.
|
|
79
|
+
- Use `loom check --network` after wiring a production release workflow so Loom
|
|
80
|
+
can verify the linked Vercel project plus GitHub's `VERCEL_TOKEN`,
|
|
81
|
+
`VERCEL_ORG_ID`, and `VERCEL_PROJECT_ID` release configuration.
|
|
82
|
+
- Use `loom db release setup-github` to create/update that GitHub release
|
|
83
|
+
configuration from the linked Vercel project, including storing a Vercel token
|
|
84
|
+
scoped to the linked team as the GitHub `VERCEL_TOKEN` environment secret.
|
|
85
|
+
- Smoke check the staged deployment URL after promotion with normal `curl`.
|
|
86
|
+
Create a short-lived Vercel Protection Bypass for Automation secret through
|
|
87
|
+
the Vercel API, send it as the `x-vercel-protection-bypass` header, and revoke
|
|
88
|
+
it in the same step. Avoid the beta `vercel curl` command in CI.
|
|
89
|
+
- Production migrations must remain backward-compatible with the currently live
|
|
90
|
+
app because old code continues serving traffic until the staged deployment is
|
|
91
|
+
promoted. Use expand/contract migrations for destructive schema changes.
|
|
92
|
+
- Keep `VERCEL_TOKEN` in a protected GitHub Environment, limit that environment
|
|
93
|
+
to release branches, and expose the token only on steps that call Vercel. Pin
|
|
94
|
+
third-party Actions to full commit SHAs and let Dependabot maintain them.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Loom DB Stack
|
|
2
|
+
|
|
3
|
+
The Loom DB feature standardizes the cross-app wiring around:
|
|
4
|
+
|
|
5
|
+
- thin wrappers for `src/db/neon.ts`
|
|
6
|
+
- thin wrappers for `src/db/neonFull.ts`
|
|
7
|
+
- thin wrappers for `drizzle.config.ts`
|
|
8
|
+
- `scripts/dump-test-tables.ts` as an app-local table-selection entrypoint
|
|
9
|
+
- thin wrappers for `tests/memory-pglite.ts`
|
|
10
|
+
- thin wrappers for `src/db/valibot/refinements/_common.ts`
|
|
11
|
+
- `src/db/valibot/index.ts`
|
|
12
|
+
- `package.json` DB scripts, including `schema:gen` and `db:fixtures`
|
|
13
|
+
|
|
14
|
+
It does not own:
|
|
15
|
+
|
|
16
|
+
- app-specific schema files or migrations
|
|
17
|
+
- local schema extensions around Loom-managed schema blueprints
|
|
18
|
+
- auth runtime setup
|
|
19
|
+
- domain-specific Valibot refinements
|
|
20
|
+
- fixture table selection policy
|
|
21
|
+
|
|
22
|
+
Schema-bearing Loom features may own versioned blueprints that are materialized
|
|
23
|
+
into committed app-local schema files. `loom db schemas sync` refreshes those
|
|
24
|
+
files only when the current file still matches the hash recorded in `loom.json`;
|
|
25
|
+
it does not generate migrations.
|
|
26
|
+
|
|
27
|
+
The intended consumer flow is:
|
|
28
|
+
|
|
29
|
+
1. `loom add db`
|
|
30
|
+
2. keep schema files app-local under the configured schema directory
|
|
31
|
+
3. keep only app-local fixture table selection in `scripts/dump-test-tables.ts`
|
|
32
|
+
4. run `loom db schema-gen`
|
|
33
|
+
5. run `loom check`
|
|
34
|
+
|
|
35
|
+
For schema-bearing feature updates:
|
|
36
|
+
|
|
37
|
+
1. run `loom db schemas sync`
|
|
38
|
+
2. review the schema diff
|
|
39
|
+
3. run the app's normal `db:generate` flow if the schema changed
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: loom-files
|
|
3
|
+
description: Use when the task touches the Loom files feature, loomFiles.ts, @gadicc/loom/files, @gadicc/loom/next/files, upload/download routes, object storage, or legacy file2 migration planning in a consuming app.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Loom Files
|
|
7
|
+
|
|
8
|
+
Use this skill when working on the shared files feature from a consuming app.
|
|
9
|
+
|
|
10
|
+
## Start here
|
|
11
|
+
|
|
12
|
+
1. Read `loom.json`.
|
|
13
|
+
2. Inspect `features.files.config.schema` and `features.db.config` before
|
|
14
|
+
assuming schema paths.
|
|
15
|
+
3. Confirm the app-local schema barrel exports the managed files schema.
|
|
16
|
+
4. Identify the app-local repository, storage, auth, route, and UI adapters.
|
|
17
|
+
|
|
18
|
+
## Ownership boundaries
|
|
19
|
+
|
|
20
|
+
- Loom owns the managed `files` schema blueprint, runtime contracts, headless
|
|
21
|
+
helpers, and route factories.
|
|
22
|
+
- The consuming app owns Drizzle migrations, repository adapter code, storage
|
|
23
|
+
provider configuration, auth/access policy, route placement, UI, and domain
|
|
24
|
+
associations.
|
|
25
|
+
- Do not edit the managed `loomFiles.ts` schema file for app-specific columns or
|
|
26
|
+
relations. Add local schema files and export them from the schema barrel.
|
|
27
|
+
- Keep file bytes in object storage and metadata in the DB. Do not store large
|
|
28
|
+
binary artifacts in DB JSON fields.
|
|
29
|
+
|
|
30
|
+
## Runtime guidance
|
|
31
|
+
|
|
32
|
+
- Use `@gadicc/loom/files` for SHA-256 hashing, digest verification, metadata
|
|
33
|
+
detection, repository/storage contracts, duplicate upload policy, and
|
|
34
|
+
content-addressed save behavior.
|
|
35
|
+
- Use `@gadicc/loom/files/s3` when the app already provides AWS SDK v3 S3 client
|
|
36
|
+
and command constructors. Enable conditional writes for content-addressed
|
|
37
|
+
private uploads when overwrites should be rejected.
|
|
38
|
+
- Use `@gadicc/loom/next/files` for App Router upload, metadata, and download
|
|
39
|
+
handlers. Prefer explicit query params or App Router route params for file
|
|
40
|
+
lookup; avoid loose path-tail inference.
|
|
41
|
+
- The default object key is the server-verified SHA-256 digest. Preserve that
|
|
42
|
+
unless the app has a clear provider-specific key policy.
|
|
43
|
+
- If file rows are user-private and there is no app-local association table yet,
|
|
44
|
+
reject duplicate SHA-256 uploads instead of reusing another user's canonical
|
|
45
|
+
row.
|
|
46
|
+
- Keep upload UI dependencies app-local. Loom helpers should remain headless.
|
|
47
|
+
|
|
48
|
+
## Cloudflare R2 and local MinIO
|
|
49
|
+
|
|
50
|
+
- Run `loom files r2 setup --account-id <id>` after activating Files. Require
|
|
51
|
+
explicit account selection when Wrangler exposes multiple Cloudflare accounts;
|
|
52
|
+
use `--cloudflare-profile` for a named Wrangler login. Persist the stable
|
|
53
|
+
account ID in `loom.json`, but keep machine-specific profile names local; pass
|
|
54
|
+
the flag per command or bind a profile to the consumer directory with
|
|
55
|
+
`wrangler auth activate`.
|
|
56
|
+
- Keep the default separate private Production and Preview buckets unless the
|
|
57
|
+
app deliberately chooses `--shared-bucket`. Do not enable public development
|
|
58
|
+
URLs, custom domains, browser-direct uploads, or CORS as part of standard
|
|
59
|
+
setup.
|
|
60
|
+
- Create an R2 Object Read & Write API token manually and scope it only to the
|
|
61
|
+
configured bucket or buckets. Use `--configure-secrets` to let Vercel prompt
|
|
62
|
+
for missing Production/Preview values without exposing them to Loom. Never
|
|
63
|
+
copy credentials into Vercel Development or commit them to the repository.
|
|
64
|
+
- Prefer local MinIO, which setup configures in gitignored `.env.local` by
|
|
65
|
+
default. Preserve existing canonical credentials and unrelated env entries. On
|
|
66
|
+
Arch, the MinIO client executable is `mcli`, from the `minio-client` package.
|
|
67
|
+
Use `--local-provider r2 --local-bucket <name>` only when shared dev files are
|
|
68
|
+
intentional, or `--local-provider none` when storage is managed separately.
|
|
69
|
+
- Setup is rerunnable and reuses existing buckets. Use `--repair` only for
|
|
70
|
+
reviewed non-secret drift; do not delete buckets or rotate credentials as a
|
|
71
|
+
repair side effect.
|
|
72
|
+
|
|
73
|
+
## Legacy migration planning
|
|
74
|
+
|
|
75
|
+
- Inventory old routes, callers, DB records, object keys, ownership semantics,
|
|
76
|
+
and domain records before replacing `file2`.
|
|
77
|
+
- Preserve existing SHA-256 object keys where possible.
|
|
78
|
+
- If old callers or domain records use Mongo ids, add an app-local alias table
|
|
79
|
+
or compatibility wrapper instead of overloading the managed files row.
|
|
80
|
+
- Migrate metadata first, then validate object existence and byte hashes before
|
|
81
|
+
switching upload/download routes.
|
|
82
|
+
- Keep `/api/file2` compatibility only while live callers need it, and route it
|
|
83
|
+
through the shared service layer.
|
|
84
|
+
|
|
85
|
+
## Verification
|
|
86
|
+
|
|
87
|
+
- Run `loom check` after changing files wiring.
|
|
88
|
+
- Run `loom files r2 check` after provider setup, or `loom check --network` to
|
|
89
|
+
include the same remote account, bucket, privacy, Vercel scope, and local
|
|
90
|
+
MinIO checks with the rest of the project.
|
|
91
|
+
- Treat generated access/storage stubs as unfinished work;
|
|
92
|
+
`loom check
|
|
93
|
+
--production` should fail while they are still present.
|
|
94
|
+
- Run `loom db schemas sync` only for managed blueprint refreshes, then review
|
|
95
|
+
diffs and generate migrations with the app's normal DB flow.
|
|
96
|
+
- Add route tests for upload, metadata lookup, authorization failures, digest
|
|
97
|
+
mismatch, dedupe, and download behavior.
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: loom-jobs
|
|
3
|
+
description: Use when the task mentions the loom jobs feature, src/jobs or jobs catalogs, /admin/jobs pages or route handlers, createJobsListPage, createJobsRunPage, createJobsRouteHandler, direct runners, or repairing loom-managed jobs wrappers in a consuming app.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Loom Jobs
|
|
7
|
+
|
|
8
|
+
Use this skill when working on the shared jobs feature from a consuming app.
|
|
9
|
+
|
|
10
|
+
## Start here
|
|
11
|
+
|
|
12
|
+
1. Read `loom.json`.
|
|
13
|
+
2. Inspect `features.jobs.config` and use the configured module and UI paths
|
|
14
|
+
instead of assuming defaults.
|
|
15
|
+
3. Check the app-local jobs catalog files before changing wrappers.
|
|
16
|
+
|
|
17
|
+
## Ownership boundaries
|
|
18
|
+
|
|
19
|
+
- App-local jobs still live in the app and remain the source of truth for job
|
|
20
|
+
definitions and app-specific rendering.
|
|
21
|
+
- Shared pages and handlers from `@gadicc/loom` should stay behind thin local
|
|
22
|
+
wrappers when the app uses the standard installation mode.
|
|
23
|
+
- New generated Jobs route wrappers use the 30-minute `maxDuration = 1800`
|
|
24
|
+
default. Override `staticRoutes.maxDuration` or a single job's `maxDuration`
|
|
25
|
+
in `loom.json` when the app needs a shorter limit.
|
|
26
|
+
- If behavior would benefit every loom consumer, fix it in the shared package
|
|
27
|
+
instead of duplicating logic in one app.
|
|
28
|
+
|
|
29
|
+
## What to preserve
|
|
30
|
+
|
|
31
|
+
- Existing custom renderers or route wrappers that intentionally extend the
|
|
32
|
+
shared helpers.
|
|
33
|
+
- The configured catalog imports, especially metadata-only exports used by the
|
|
34
|
+
jobs list page.
|
|
35
|
+
- Direct-runner settings and script paths when the app has opted into them.
|
|
36
|
+
- Direct job runners should assume env has already been loaded by the package
|
|
37
|
+
script. Keep env loading in scripts such as `job` via `loom env --`, not in
|
|
38
|
+
`scripts/jobDirect.ts`.
|
|
39
|
+
|
|
40
|
+
## Catalog runtime boundaries
|
|
41
|
+
|
|
42
|
+
- Keep the configured metadata catalog dependency-free. Define job metadata in a
|
|
43
|
+
neutral module and re-export it from each implementation; do not re-export
|
|
44
|
+
`meta` from implementation modules into `indexWithMetaOnly.ts`.
|
|
45
|
+
- Build executable catalog entries with `createLazyJob` and a literal dynamic
|
|
46
|
+
import so Next.js can identify each boundary while the route evaluates only
|
|
47
|
+
the selected implementation:
|
|
48
|
+
```ts
|
|
49
|
+
export const example = createLazyJob(exampleMeta, () => import("./example"));
|
|
50
|
+
```
|
|
51
|
+
- Do not use eager `export * as job from "./job"` barrels for HTTP catalogs. A
|
|
52
|
+
single optional or worker-only dependency would then initialize when any
|
|
53
|
+
unrelated job route is requested.
|
|
54
|
+
- A job that supports both an in-process and worker-only runtime should also
|
|
55
|
+
load its worker executor only after the persisted execution target selects
|
|
56
|
+
that runtime.
|
|
57
|
+
- When deployment tracing must isolate large or worker-only dependencies, use
|
|
58
|
+
one static App Router route per job with `createJobRouteHandler({ job })`.
|
|
59
|
+
`createLazyJob` prevents eager runtime evaluation, but one dynamic `[id]`
|
|
60
|
+
route is still one serverless function whose trace includes every reachable
|
|
61
|
+
job implementation.
|
|
62
|
+
- Configure `features.jobs.config.staticRoutes` with the HTTP job-to-module map,
|
|
63
|
+
then run `loom add jobs` to synchronize marker-owned route wrappers. Loom
|
|
64
|
+
preserves unmanaged collisions and `loom check` reports missing, stale, or
|
|
65
|
+
edited managed routes.
|
|
66
|
+
- Keep `maxDuration` as a direct positive integer export in every App Router
|
|
67
|
+
route file. Next.js does not reliably include a re-exported route segment
|
|
68
|
+
config in deployment metadata; Loom-generated routes therefore declare the
|
|
69
|
+
configured literal locally.
|
|
70
|
+
|
|
71
|
+
## HTTP authorization and API keys
|
|
72
|
+
|
|
73
|
+
- The optional `createJobsRouteHandler` authorization callback protects remote
|
|
74
|
+
HTTP execution. Configure the app's fresh session/admin policy before adding
|
|
75
|
+
any API-key branch.
|
|
76
|
+
- API-key foundation installation does not change jobs. Opt in explicitly with
|
|
77
|
+
`loom api-keys integrate jobs --resource <resource> --action <action>` and
|
|
78
|
+
preserve the existing session/admin branch.
|
|
79
|
+
- Use `authorizeSessionOrApiKeyRequest` plus `completeApiKeyAuthorizedResponse`
|
|
80
|
+
for auditable response creation without buffering job streams.
|
|
81
|
+
- GET and POST remain supported; a future POST-only change requires a separate
|
|
82
|
+
compatibility migration.
|
|
83
|
+
- The direct local runner imports the catalog and executes inside the trusted
|
|
84
|
+
shell process with local environment/database access. It remains API-key-free.
|
|
85
|
+
A future command that calls a deployed HTTP route is a remote client and must
|
|
86
|
+
authenticate.
|
|
87
|
+
|
|
88
|
+
## Diagnosing queued work
|
|
89
|
+
|
|
90
|
+
- Distinguish the control-plane action that queues a job from the worker or
|
|
91
|
+
runner that actually processes it.
|
|
92
|
+
- When a job-backed workflow fails, inspect durable job/run state before
|
|
93
|
+
inferring from UI status alone: run rows, checkpoints, artifacts, persisted
|
|
94
|
+
metadata, logs, and the trigger that created the run.
|
|
95
|
+
- For resume or challenge flows, verify which state is saved for the suspended
|
|
96
|
+
run and which follow-up trigger is expected to consume it.
|
|
97
|
+
- If the app has no always-on worker in the current environment, call out the
|
|
98
|
+
manual runner or admin route needed to drain queued work.
|
|
99
|
+
|
|
100
|
+
## Job Parameters and Validation
|
|
101
|
+
|
|
102
|
+
Loom supports declarative job parameter definitions on each job's `meta` object.
|
|
103
|
+
When adding or upgrading a job:
|
|
104
|
+
|
|
105
|
+
- **Declare Parameters**: Specify `params` on the job `meta` object with their
|
|
106
|
+
`type` (`"string" | "number" | "boolean"`), `desc`, and optional `default` or
|
|
107
|
+
`required` flags.
|
|
108
|
+
```typescript
|
|
109
|
+
export const meta: Job["meta"] = {
|
|
110
|
+
id: "my-job",
|
|
111
|
+
desc: "My job description",
|
|
112
|
+
params: {
|
|
113
|
+
count: {
|
|
114
|
+
type: "number",
|
|
115
|
+
desc: "Number of times to run",
|
|
116
|
+
default: 5,
|
|
117
|
+
},
|
|
118
|
+
verbose: {
|
|
119
|
+
type: "boolean",
|
|
120
|
+
desc: "Enable verbose logs",
|
|
121
|
+
default: false,
|
|
122
|
+
},
|
|
123
|
+
},
|
|
124
|
+
};
|
|
125
|
+
```
|
|
126
|
+
- **Upgrade Old-Style Params**: If you are working on an existing job that
|
|
127
|
+
accesses parameters from raw query/string objects (e.g. using
|
|
128
|
+
`Number(params.count)` or `params.resetStale === "true"` manually), **upgrade
|
|
129
|
+
it** to use declarative `params` metadata. This removes manual type
|
|
130
|
+
casting/checking boilerplate from the handler and improves safety.
|
|
131
|
+
- **Scaffolding and UI**: Declaring parameters will automatically:
|
|
132
|
+
1. Render a premium parameters form on the Next.js admin `/run` page with
|
|
133
|
+
hover tooltips and default placeholders.
|
|
134
|
+
2. Perform automatic type validation on Next.js API routes (returning
|
|
135
|
+
`400 Bad Request` on invalid inputs).
|
|
136
|
+
3. Validate options and print a beautiful `--help` option menu in the CLI
|
|
137
|
+
`jobDirect` runner.
|
|
138
|
+
|
|
139
|
+
## Verification
|
|
140
|
+
|
|
141
|
+
- Run `loom check` after changes.
|
|
142
|
+
- Confirm local wrappers still point at the configured shared modules.
|
|
143
|
+
- Confirm the jobs modules still use the shared helpers: `createJobsListPage`,
|
|
144
|
+
`createJobsRunPage`, and `createJobsRouteHandler`.
|
|
145
|
+
- Confirm executable catalog entries use `createLazyJob` and the metadata
|
|
146
|
+
catalog does not import job implementations.
|
|
147
|
+
- Confirm the `job` package script runs the direct runner through `loom env --`
|
|
148
|
+
and that the direct-runner file does not import `dotenv` or `@next/env`.
|