@fabrika/builder 0.9.0-dev.1 → 0.9.0-dev.10
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 +1 -1
- package/cli/src/inject-skills.ts +2 -2
- package/cli/src/skeletons.ts +2 -2
- package/daemon/src/handlers.ts +1 -1
- package/daemon/src/platform-remote.ts +1 -1
- package/decisions/README.md +20 -20
- package/decisions/patterns/app-deploy.md +6 -6
- package/decisions/patterns/{vozka-app-deploy.md → fabrika-app-deploy.md} +24 -24
- package/decisions/patterns/single-worker-spa.md +2 -2
- package/decisions/patterns/typed-worker-rpc.md +3 -3
- package/decisions/patterns/zerops-control-deploy.md +1 -1
- package/decisions/technologies/buzola.md +2 -2
- package/decisions/technologies/cloudflare-access.md +5 -5
- package/decisions/technologies/cloudflare.md +1 -1
- package/decisions/technologies/contember.md +1 -1
- package/decisions/technologies/{vozka.md → fabrika-control.md} +35 -30
- package/decisions/technologies/{propustka.md → fabrika-iam.md} +17 -17
- package/decisions/technologies/lopata.md +1 -1
- package/decisions/technologies/oblaka.md +6 -6
- package/decisions/technologies/workers-ai.md +1 -1
- package/decisions/technologies/wrangler.md +2 -2
- package/decisions/technologies/zerops-fabrika-auth.md +2 -2
- package/decisions/technologies/zerops-platform.md +4 -3
- package/package.json +12 -11
- package/skill/SKILL.md +1 -1
- package/skill/gates/tech.jsx +1 -1
- package/stacks/README.md +1 -1
- package/stacks/cf-internal-app.md +22 -22
- package/types/cli/src/bin.d.ts +3 -0
- package/types/cli/src/build-status.d.ts +20 -0
- package/types/cli/src/catalog.d.ts +9 -0
- package/types/cli/src/commands/advance.d.ts +1 -0
- package/types/cli/src/commands/build.d.ts +1 -0
- package/types/cli/src/commands/ensure-daemon.d.ts +1 -0
- package/types/cli/src/commands/gate.d.ts +1 -0
- package/types/cli/src/commands/induce.d.ts +1 -0
- package/types/cli/src/commands/init.d.ts +1 -0
- package/types/cli/src/commands/next.d.ts +1 -0
- package/types/cli/src/commands/platform.d.ts +2 -0
- package/types/cli/src/config.d.ts +16 -0
- package/types/cli/src/context.d.ts +13 -0
- package/types/cli/src/daemon-client.d.ts +36 -0
- package/types/cli/src/daemon-lifecycle.d.ts +16 -0
- package/types/cli/src/derive.d.ts +17 -0
- package/types/cli/src/errors.d.ts +2 -0
- package/types/cli/src/index.d.ts +7 -0
- package/types/cli/src/induce.d.ts +16 -0
- package/types/cli/src/inject-skills.d.ts +23 -0
- package/types/cli/src/issues.d.ts +12 -0
- package/types/cli/src/layout.d.ts +21 -0
- package/types/cli/src/packet.d.ts +32 -0
- package/types/cli/src/phase-state.d.ts +6 -0
- package/types/cli/src/platform-client.d.ts +24 -0
- package/types/cli/src/skeletons.d.ts +11 -0
- package/types/daemon/src/admission.d.ts +1 -0
- package/types/daemon/src/bin.d.ts +2 -0
- package/types/daemon/src/build-stream.d.ts +14 -0
- package/types/daemon/src/handlers.d.ts +15 -0
- package/types/daemon/src/index.d.ts +23 -0
- package/types/daemon/src/paths.d.ts +10 -0
- package/types/daemon/src/phases.d.ts +21 -0
- package/types/daemon/src/platform-compiler.d.ts +1 -0
- package/types/daemon/src/platform-remote.d.ts +309 -0
- package/types/daemon/src/platform-routes.d.ts +3 -0
- package/types/daemon/src/platform-source.d.ts +7 -0
- package/types/daemon/src/platform-storage.d.ts +38 -0
- package/types/daemon/src/platform.d.ts +43 -0
- package/types/daemon/src/static.d.ts +2 -0
- package/types/index.d.ts +2 -0
- package/types/shared/index.d.ts +2324 -0
- package/types/shared/phases.d.ts +25 -0
- package/types/shared/urls.d.ts +4 -0
- package/ui/dist/assets/client.mh3w1dvc.js +214 -0
- package/ui/dist/index.html +1 -1
- package/ui/dist/assets/client.j37h210g.js +0 -214
package/README.md
CHANGED
|
@@ -55,7 +55,7 @@ fabrika builder induce [--force]
|
|
|
55
55
|
fabrika builder build [--issue <ID>] [--assisted]
|
|
56
56
|
```
|
|
57
57
|
|
|
58
|
-
Use `--profile cf-internal-app` for the full Buzola,
|
|
58
|
+
Use `--profile cf-internal-app` for the full Buzola, Fabrika IAM, and Fabrika Control internal-app stack. The default is `cf-lightweight`.
|
|
59
59
|
|
|
60
60
|
Connected initialization uses `zerops-app` for a new project. A person approves the application and environment in the installed console; the local daemon receives a thirty-day app-scoped credential. The agent and application stay local. Deployment requires a clean, remotely available Git revision and runs through Control. `disconnect` removes the local key only; revoke server access in the console. See [the connected workflow](../../docs/reference/local-builder.md) for prerequisites, custody and recovery.
|
|
61
61
|
|
package/cli/src/inject-skills.ts
CHANGED
|
@@ -237,8 +237,8 @@ function tomlString(value: string): string {
|
|
|
237
237
|
}
|
|
238
238
|
|
|
239
239
|
function tomlMultiline(value: string): string {
|
|
240
|
-
const escaped = value.replace(/\\/g, '\\\\').replace(
|
|
241
|
-
return
|
|
240
|
+
const escaped = value.replace(/\\/g, '\\\\').replace(/"""/g, '\\"\\"\\"')
|
|
241
|
+
return `"""\n${escaped}"""`
|
|
242
242
|
}
|
|
243
243
|
|
|
244
244
|
function installManagedFile(
|
package/cli/src/skeletons.ts
CHANGED
|
@@ -15,7 +15,7 @@ export function readSkeletons(testsBrowserDir: string): Skeleton[] {
|
|
|
15
15
|
if (!existsSync(testsBrowserDir) || !statSync(testsBrowserDir).isDirectory()) return []
|
|
16
16
|
const out: Skeleton[] = []
|
|
17
17
|
for (const entry of readdirSync(testsBrowserDir).sort()) {
|
|
18
|
-
if (
|
|
18
|
+
if (!entry.endsWith('.test.ts')) continue
|
|
19
19
|
const file = join(testsBrowserDir, entry)
|
|
20
20
|
if (!statSync(file).isFile() || statSync(file).size === 0) continue
|
|
21
21
|
out.push(...parseSkeletons(file))
|
|
@@ -51,7 +51,7 @@ export function parseSkeletons(file: string): Skeleton[] {
|
|
|
51
51
|
}
|
|
52
52
|
|
|
53
53
|
function strField(meta: string, key: string): string | undefined {
|
|
54
|
-
const re = new RegExp(`\\b${key}\\s*:\\s*([\`'
|
|
54
|
+
const re = new RegExp(`\\b${key}\\s*:\\s*([\`'"])([\\s\\S]*?)\\1`)
|
|
55
55
|
const m = meta.match(re)
|
|
56
56
|
return m ? m[2] : undefined
|
|
57
57
|
}
|
package/daemon/src/handlers.ts
CHANGED
|
@@ -298,7 +298,7 @@ export function createHandlers(ctx: HandlerContext): Route[] {
|
|
|
298
298
|
|
|
299
299
|
const skeletons: unknown[] = []
|
|
300
300
|
for (const entry of readdirSync(dir).sort()) {
|
|
301
|
-
if (
|
|
301
|
+
if (!entry.endsWith('.test.ts')) continue
|
|
302
302
|
try {
|
|
303
303
|
platform.storage.artifact(session.projectRoot, join('tests', 'browser', entry))
|
|
304
304
|
platform.storage.assertPublicFile(join(dir, entry))
|
|
@@ -101,7 +101,7 @@ export async function boundedJson(response: Response): Promise<unknown> {
|
|
|
101
101
|
}
|
|
102
102
|
|
|
103
103
|
export class PlatformRemote {
|
|
104
|
-
constructor(private readonly fetcher: RpcFetch = fetch, readonly signal: AbortSignal) {}
|
|
104
|
+
constructor(private readonly fetcher: RpcFetch = (input, init) => fetch(input, init), readonly signal: AbortSignal) {}
|
|
105
105
|
|
|
106
106
|
async json(url: string, body?: unknown): Promise<unknown> {
|
|
107
107
|
try {
|
package/decisions/README.md
CHANGED
|
@@ -72,8 +72,8 @@ sources: # live truth to READ before scaffolding (anti-stalenes
|
|
|
72
72
|
|
|
73
73
|
## The three edge types (everything the graph needs)
|
|
74
74
|
|
|
75
|
-
- **`requires`** — hard dependency. Pick A ⇒ B must be in the stack. `
|
|
76
|
-
{cloudflare, oblaka, wrangler,
|
|
75
|
+
- **`requires`** — hard dependency. Pick A ⇒ B must be in the stack. `fabrika-control →
|
|
76
|
+
{cloudflare, oblaka, wrangler, fabrika-iam}`, `buzola → react`, `write-split → analytics-engine`.
|
|
77
77
|
- **`recommends`** — soft suggestion. Pick A ⇒ offer B. `cloudflare → d1, durable-objects`.
|
|
78
78
|
- **`conflicts`** — declared incompatibility. `buzola ✕ react-router` (both routers).
|
|
79
79
|
Often _implied_ by two decisions sharing an exclusive **`slot`**, so `conflicts` is
|
|
@@ -97,23 +97,23 @@ See `../stacks/README.md`.
|
|
|
97
97
|
|
|
98
98
|
### Technologies (`technologies/`)
|
|
99
99
|
|
|
100
|
-
| slot / area | decisions
|
|
101
|
-
| ---------------------------------- |
|
|
102
|
-
| platform / edge auth | `cloudflare`, `cloudflare-access` (legacy alternative to native
|
|
103
|
-
| relational store (`relational-db`) | `d1`, `postgres`
|
|
104
|
-
| storage / state | `kv`, `r2`, `durable-objects`, `analytics-engine`
|
|
105
|
-
| messaging / jobs | `queue`, `cron-triggers`
|
|
106
|
-
| AI runtime | `workers-ai`
|
|
107
|
-
| runtime / build / iac / deploy | `bun`, `vite`, `lopata`, `cloudflare-vite-plugin`, `oblaka`, `wrangler`, `
|
|
108
|
-
| ui framework | `react`, `preact`
|
|
109
|
-
| router | `react-router`, `buzola`
|
|
110
|
-
| styling | `tailwind`
|
|
111
|
-
| backend / data API (`backend`) | `contember`, `bindx`
|
|
112
|
-
| site / content (`site-framework`) | `pletivo`, `nuasite`
|
|
113
|
-
| agents (`agent-sdk`) | `roj`
|
|
114
|
-
| native authn/authz | `
|
|
115
|
-
| error tracking (`error-tracking`) | `sentry`
|
|
116
|
-
| testing | `opice`
|
|
100
|
+
| slot / area | decisions |
|
|
101
|
+
| ---------------------------------- | ------------------------------------------------------------------------------------------ |
|
|
102
|
+
| platform / edge auth | `cloudflare`, `cloudflare-access` (legacy alternative to native Fabrika IAM) |
|
|
103
|
+
| relational store (`relational-db`) | `d1`, `postgres` |
|
|
104
|
+
| storage / state | `kv`, `r2`, `durable-objects`, `analytics-engine` |
|
|
105
|
+
| messaging / jobs | `queue`, `cron-triggers` |
|
|
106
|
+
| AI runtime | `workers-ai` |
|
|
107
|
+
| runtime / build / iac / deploy | `bun`, `vite`, `lopata`, `cloudflare-vite-plugin`, `oblaka`, `wrangler`, `fabrika-control` |
|
|
108
|
+
| ui framework | `react`, `preact` |
|
|
109
|
+
| router | `react-router`, `buzola` |
|
|
110
|
+
| styling | `tailwind` |
|
|
111
|
+
| backend / data API (`backend`) | `contember`, `bindx` |
|
|
112
|
+
| site / content (`site-framework`) | `pletivo`, `nuasite` |
|
|
113
|
+
| agents (`agent-sdk`) | `roj` |
|
|
114
|
+
| native authn/authz | `fabrika-iam` |
|
|
115
|
+
| error tracking (`error-tracking`) | `sentry` |
|
|
116
|
+
| testing | `opice` |
|
|
117
117
|
|
|
118
118
|
The platform-managed Zerops path adds [`zerops-platform`](technologies/zerops-platform.md) and [`zerops-fabrika-auth`](technologies/zerops-fabrika-auth.md).
|
|
119
119
|
|
|
@@ -127,7 +127,7 @@ Applied _over_ the technologies they `require` (no package; `kind: pattern`).
|
|
|
127
127
|
| data / seeds | `named-seeds` |
|
|
128
128
|
| CF write patterns | `count-store`, `write-split` |
|
|
129
129
|
| auth | `auth-password-kv` |
|
|
130
|
-
| CI / CD | `app-deploy` (direct), `
|
|
130
|
+
| CI / CD | `app-deploy` (direct), `fabrika-app-deploy` (control plane), `lib-publish` |
|
|
131
131
|
| observability | `structured-logging`, `observability` |
|
|
132
132
|
|
|
133
133
|
Zerops composition uses [`zerops-local-app`](patterns/zerops-local-app.md), [`zerops-control-deploy`](patterns/zerops-control-deploy.md), and [`zerops-postgres-seeds`](patterns/zerops-postgres-seeds.md).
|
|
@@ -6,7 +6,7 @@ slot: null
|
|
|
6
6
|
provides: [ci-deploy, cf-deploy, infra-provisioning]
|
|
7
7
|
requires: [cloudflare, oblaka, wrangler]
|
|
8
8
|
recommends: []
|
|
9
|
-
conflicts: [
|
|
9
|
+
conflicts: [fabrika-app-deploy]
|
|
10
10
|
status: stable
|
|
11
11
|
sources:
|
|
12
12
|
- where: "opice — .github/workflows/deploy.yml (the canonical app-deploy workflow)"
|
|
@@ -28,13 +28,13 @@ bindings (D1/KV/R2/DO/AE) via the CF API and emit `wrangler.jsonc`, then
|
|
|
28
28
|
chosen from the branch, with a concurrency lock per environment.
|
|
29
29
|
|
|
30
30
|
This is the **direct per-repository alternative** for accounts/apps not managed by
|
|
31
|
-
|
|
31
|
+
Fabrika Control. Do not scaffold it alongside `fabrika-app-deploy`.
|
|
32
32
|
|
|
33
33
|
## When & why to use
|
|
34
34
|
|
|
35
|
-
- A Cloudflare app whose target account is **not** managed by
|
|
35
|
+
- A Cloudflare app whose target account is **not** managed by Fabrika Control — deploy is a
|
|
36
36
|
git push to the env branch, with infra-as-code and no dashboard clicking.
|
|
37
|
-
- Prefer `
|
|
37
|
+
- Prefer `fabrika-app-deploy` when the target account already has Fabrika Control + Fabrika IAM.
|
|
38
38
|
|
|
39
39
|
## When NOT to use
|
|
40
40
|
|
|
@@ -46,10 +46,10 @@ Vozka. Do not scaffold it alongside `vozka-app-deploy`.
|
|
|
46
46
|
- **Migrations run at deploy time** (`--remote`), not before — a failed migration fails the deploy; keep them idempotent.
|
|
47
47
|
- **Per-env from the branch** — `main`→stage, `deploy/prod`→prod; the GitHub `environment` gates secrets + serializes concurrent deploys.
|
|
48
48
|
- Never hand-edit the generated `wrangler.jsonc` — change `oblaka.ts`.
|
|
49
|
-
- Never run this workflow and
|
|
49
|
+
- Never run this workflow and Fabrika Control against the same target during normal
|
|
50
50
|
operation; their locks do not coordinate.
|
|
51
51
|
|
|
52
52
|
## Relationships — why
|
|
53
53
|
|
|
54
54
|
- **requires `cloudflare` + `oblaka` + `wrangler`** — it's exactly the oblaka→wrangler.jsonc→wrangler-deploy chain on CF. Pairs with `lib-publish` (the other half of CI) in a monorepo.
|
|
55
|
-
- **conflicts `
|
|
55
|
+
- **conflicts `fabrika-app-deploy`** — one app/environment must have one deploy owner.
|
|
@@ -1,74 +1,74 @@
|
|
|
1
1
|
---
|
|
2
|
-
id:
|
|
2
|
+
id: fabrika-app-deploy
|
|
3
3
|
kind: pattern
|
|
4
|
-
title: App deploy —
|
|
4
|
+
title: App deploy — Fabrika-managed Cloudflare lifecycle
|
|
5
5
|
slot: null
|
|
6
6
|
provides: [ci-deploy, cf-deploy, infra-provisioning, schema-reconciliation, secret-sync]
|
|
7
|
-
requires: [
|
|
7
|
+
requires: [fabrika-control, fabrika-iam, oblaka, wrangler]
|
|
8
8
|
recommends: []
|
|
9
9
|
conflicts: [app-deploy]
|
|
10
10
|
status: wip
|
|
11
11
|
sources:
|
|
12
|
-
- where: "
|
|
12
|
+
- where: "the predecessor control-plane repository — MIGRATION.md + packages/core/src/{plan,deploy}.ts"
|
|
13
13
|
read: "Registry fields, trigger routing, deploy locks, step order, state continuity and migration/cut-over rules."
|
|
14
|
-
- where: "
|
|
15
|
-
read: "A native-
|
|
14
|
+
- where: "the predecessor control-plane examples"
|
|
15
|
+
read: "A native-IAM app shape with one resource graph plus its schema, build, and secrets pipeline."
|
|
16
16
|
---
|
|
17
17
|
|
|
18
|
-
#
|
|
18
|
+
# Fabrika-managed app deploy
|
|
19
19
|
|
|
20
20
|
## What it is
|
|
21
21
|
|
|
22
22
|
The application repository declares its complete deploy surface in
|
|
23
|
-
`
|
|
23
|
+
`fabrika.config.ts`; the account's Fabrika Control plane owns GitHub triggers/manual
|
|
24
24
|
runs, deploy credentials, per-app/per-env locking, logs and execution. The app no
|
|
25
|
-
longer maintains a workflow that manually sequences oblaka, wrangler,
|
|
25
|
+
longer maintains a workflow that manually sequences oblaka, wrangler, Fabrika IAM
|
|
26
26
|
and secrets.
|
|
27
27
|
|
|
28
28
|
## Scaffold contract
|
|
29
29
|
|
|
30
|
-
- Commit `
|
|
31
|
-
`resources(ctx)`, optional
|
|
30
|
+
- Commit `fabrika.config.ts` with a stable app `id`, environment-neutral
|
|
31
|
+
`resources(ctx)`, optional Fabrika IAM `schema`, and `pipeline`.
|
|
32
32
|
- Export the resource builder for the local `oblaka.ts` shim so the graph does
|
|
33
33
|
not drift between lopata and production.
|
|
34
34
|
- Read the production hostname from `ctx.domain`.
|
|
35
35
|
- Bind `IAM: ServiceReference('propustka-worker')` only off-local; set a single
|
|
36
36
|
explicit local-dev flag for the app's deterministic auth context.
|
|
37
|
-
- Declare third-party runtime secrets in `pipeline.secrets`.
|
|
38
|
-
Cloudflare credentials and the
|
|
37
|
+
- Declare third-party runtime secrets in `pipeline.secrets`. Fabrika Control platform
|
|
38
|
+
Cloudflare credentials and the Fabrika IAM provisioning key are not app secrets.
|
|
39
39
|
- Register repository, environment, domain, trigger ref and secret values in
|
|
40
|
-
the target account's
|
|
40
|
+
the target account's Fabrika Control. That external registration is an operator step,
|
|
41
41
|
not committed application config.
|
|
42
42
|
|
|
43
|
-
## Deploy order (owned by
|
|
43
|
+
## Deploy order (owned by Fabrika Control)
|
|
44
44
|
|
|
45
45
|
1. run `pipeline.build`,
|
|
46
46
|
2. provision/materialize the oblaka resource graph into `wrangler.jsonc`,
|
|
47
47
|
3. apply every declared D1 migration remotely,
|
|
48
48
|
4. run `wrangler deploy`,
|
|
49
|
-
5. reconcile the
|
|
49
|
+
5. reconcile the Fabrika IAM authz schema,
|
|
50
50
|
6. sync declared Worker secrets.
|
|
51
51
|
|
|
52
|
-
The exact plan comes from the installed
|
|
52
|
+
The exact plan comes from the installed Fabrika Control engine. Do not reproduce this
|
|
53
53
|
sequence in a parallel GitHub Actions workflow.
|
|
54
54
|
|
|
55
55
|
## Migration/cut-over gotchas
|
|
56
56
|
|
|
57
|
-
- Preserve `<app-id>-state`; dry-run and verify that the first
|
|
57
|
+
- Preserve `<app-id>-state`; dry-run and verify that the first Fabrika Control deploy sees
|
|
58
58
|
existing resources instead of creating replacements.
|
|
59
59
|
- The first schema reconcile should be a no-op. Diff committed actions/scopes/
|
|
60
|
-
roles against live
|
|
61
|
-
- A multi-account app is registered in multiple independent
|
|
60
|
+
roles against live Fabrika IAM before cut-over.
|
|
61
|
+
- A multi-account app is registered in multiple independent Fabrika Control instances;
|
|
62
62
|
branch/ref routing decides which account acts on a push.
|
|
63
63
|
- During migration, only one deploy path may own a target. Delete the old
|
|
64
|
-
workflow after a real
|
|
65
|
-
-
|
|
64
|
+
workflow after a real Fabrika Control deploy is green, not before.
|
|
65
|
+
- Fabrika Control is 0.x: verify current dry-run credential/network requirements instead
|
|
66
66
|
of assuming a dry-run is offline.
|
|
67
67
|
|
|
68
68
|
## Relationships — why
|
|
69
69
|
|
|
70
|
-
- **requires `
|
|
71
|
-
- **requires `
|
|
70
|
+
- **requires `fabrika-control`**, which orchestrates **`oblaka` + `wrangler`**.
|
|
71
|
+
- **requires `fabrika-iam`** because schema reconciliation and the ecosystem's
|
|
72
72
|
control-plane authentication are part of this lifecycle.
|
|
73
73
|
- **conflicts `app-deploy`** — that pattern is the direct per-repo workflow
|
|
74
74
|
alternative. One target must not deploy through both.
|
|
@@ -5,7 +5,7 @@ title: Single-Worker SPA in production, split frontend/backend in development
|
|
|
5
5
|
slot: app-delivery-shape
|
|
6
6
|
provides: [spa-hosting, worker-api, local-dev-split, single-deployable]
|
|
7
7
|
requires: [cloudflare, vite, buzola]
|
|
8
|
-
recommends: [lopata,
|
|
8
|
+
recommends: [lopata, fabrika-control]
|
|
9
9
|
conflicts: []
|
|
10
10
|
status: stable
|
|
11
11
|
sources:
|
|
@@ -70,5 +70,5 @@ deployable Worker in production:
|
|
|
70
70
|
- **requires `buzola` + `vite`** — this is specifically a client-rendered Buzola
|
|
71
71
|
bundle served by Vite locally and built as Worker assets.
|
|
72
72
|
- **requires `cloudflare`** — production delivery uses a Worker assets binding.
|
|
73
|
-
- **recommends `lopata`** for the local Worker and **`
|
|
73
|
+
- **recommends `lopata`** for the local Worker and **`fabrika-control`** for the single
|
|
74
74
|
production deployable.
|
|
@@ -5,7 +5,7 @@ title: Typed SPA-to-Worker RPC boundary
|
|
|
5
5
|
slot: client-worker-api
|
|
6
6
|
provides: [typed-rpc, client-worker-api, validated-input, centralized-auth]
|
|
7
7
|
requires: [cloudflare, buzola]
|
|
8
|
-
recommends: [
|
|
8
|
+
recommends: [fabrika-iam]
|
|
9
9
|
conflicts: []
|
|
10
10
|
status: stable
|
|
11
11
|
sources:
|
|
@@ -64,7 +64,7 @@ type InferRpcMethods<M> = {
|
|
|
64
64
|
path or instantiate a handler from user input.
|
|
65
65
|
- Normalize known failures (validation 400, unauthorized 401, forbidden 403,
|
|
66
66
|
not found 404); log unexpected errors server-side and return a safe 500.
|
|
67
|
-
- With
|
|
67
|
+
- With Fabrika IAM, preserve `loginUrl` in the 401 envelope and attach a returned
|
|
68
68
|
`setCookie` to the final RPC response. The SPA redirects a human miss to login
|
|
69
69
|
and guards against redirect loops.
|
|
70
70
|
- Use relative `/rpc` URLs. The Vite proxy owns the local backend origin; this
|
|
@@ -83,5 +83,5 @@ exercise the envelope/auth seam in a smaller set of integration tests.
|
|
|
83
83
|
- **requires `cloudflare`** — the server side is the app Worker.
|
|
84
84
|
- **requires `buzola`** — the client surface is designed for loaders + SPA
|
|
85
85
|
mutations, not SSR actions.
|
|
86
|
-
- **recommends `
|
|
86
|
+
- **recommends `fabrika-iam`** — central boundary authentication plus per-method
|
|
87
87
|
capability checks is the intended secure shape.
|
|
@@ -6,7 +6,7 @@ slot: deploy-control-plane
|
|
|
6
6
|
provides: [managed-deploy, release-tracking]
|
|
7
7
|
requires: [zerops-platform, zerops-fabrika-auth]
|
|
8
8
|
recommends: []
|
|
9
|
-
conflicts: [app-deploy,
|
|
9
|
+
conflicts: [app-deploy, fabrika-app-deploy]
|
|
10
10
|
status: wip
|
|
11
11
|
sources:
|
|
12
12
|
- where: "packages/control-contract/src/rpc.ts + packages/provider-zerops/src/provider.ts in fabrika-platform"
|
|
@@ -14,7 +14,7 @@ sources:
|
|
|
14
14
|
read: "The createPage() builder + the React surface (useNavigate/useParams/useRoute, Link, Outlet, BuzolaProvider)."
|
|
15
15
|
- where: "buzola/packages/{vite-plugin,bun-plugin,codegen}/src/"
|
|
16
16
|
read: "How codegen emits src/buzola.gen.ts + the virtual:buzola/routes module, wired via EITHER the vite-plugin OR the bun-plugin (the non-vite path)."
|
|
17
|
-
- where: "
|
|
17
|
+
- where: "the predecessor IAM repository's packages/admin-ui/src/{buzola.gen.ts,routes/principals/detail.tsx,routes/_layout.tsx}"
|
|
18
18
|
read: "A real app: codegen output, chained loaders + error boundary + type-safe Link, layout nesting."
|
|
19
19
|
---
|
|
20
20
|
|
|
@@ -26,7 +26,7 @@ A **type-safe SPA router for React** built over the browser **Navigation API**,
|
|
|
26
26
|
**file-based routing** and **type codegen**. Routes are defined with a `createPage()`
|
|
27
27
|
builder; codegen emits `src/buzola.gen.ts` + a `virtual:buzola/routes` module and
|
|
28
28
|
augments a `BuzolaPageMap` so `navigate(pageId, params)` and `<Link to params>` are
|
|
29
|
-
fully typechecked. It is suitable for Contember-style admin SPAs, including
|
|
29
|
+
fully typechecked. It is suitable for Contember-style admin SPAs, including the predecessor IAM's public admin UI.
|
|
30
30
|
Ships **both** a `@buzola/vite-plugin` and a **`@buzola/bun-plugin`** — the bun-plugin
|
|
31
31
|
is the **non-vite path** that fits our bun preference.
|
|
32
32
|
|
|
@@ -6,14 +6,14 @@ slot: authentication
|
|
|
6
6
|
provides: [authentication, sso]
|
|
7
7
|
requires: [cloudflare]
|
|
8
8
|
recommends: []
|
|
9
|
-
conflicts: [auth-password-kv,
|
|
9
|
+
conflicts: [auth-password-kv, fabrika-iam]
|
|
10
10
|
npm: ["jose@^5"]
|
|
11
11
|
status: stable
|
|
12
12
|
sources:
|
|
13
13
|
- where: "developers.cloudflare.com/cloudflare-one/policies/access (Access JWT, application audience, identity)"
|
|
14
14
|
read: "How Access fronts a Worker, the JWT it injects, and how to validate it (aud/iss, JWKS)."
|
|
15
15
|
- where: "A legacy app that still uses Access JWT validation"
|
|
16
|
-
read: "A live example of validating the Access JWT and resolving identity downstream; do not copy it into native
|
|
16
|
+
read: "A live example of validating the Access JWT and resolving identity downstream; do not copy it into native Fabrika IAM apps."
|
|
17
17
|
---
|
|
18
18
|
|
|
19
19
|
# Cloudflare Access (authentication)
|
|
@@ -24,13 +24,13 @@ Cloudflare's zero-trust **authentication** layer sitting in front of a Worker. I
|
|
|
24
24
|
handles "who you are" (SSO / IdP / one-time PIN), injects a signed JWT, and the
|
|
25
25
|
Worker validates it (via `jose` — `aud`, `iss`, JWKS). It owns _authentication
|
|
26
26
|
only_. This is now the legacy/alternate front door for apps that have **not**
|
|
27
|
-
adopted native
|
|
27
|
+
adopted native Fabrika IAM sessions.
|
|
28
28
|
|
|
29
29
|
## When & why to use
|
|
30
30
|
|
|
31
31
|
- Self-hosted / internal tools where you want SSO without building login yourself.
|
|
32
32
|
- You intentionally keep an older Access-fronted app and are not migrating it to
|
|
33
|
-
native
|
|
33
|
+
native Fabrika IAM sessions yet.
|
|
34
34
|
|
|
35
35
|
## When NOT to use
|
|
36
36
|
|
|
@@ -45,6 +45,6 @@ adopted native Propustka sessions.
|
|
|
45
45
|
|
|
46
46
|
## Relationships — why
|
|
47
47
|
|
|
48
|
-
- **conflicts `
|
|
48
|
+
- **conflicts `fabrika-iam`** — current Fabrika IAM owns native SSO sessions and
|
|
49
49
|
request authorization; it no longer expects a Cloudflare Access edge.
|
|
50
50
|
- **conflicts `auth-password-kv`** — both fill the `authentication` slot. Access = managed SSO; auth-password-kv = app-owned password+session. Pick one.
|
|
@@ -40,7 +40,7 @@ Workers with first-party bindings to storage and messaging primitives
|
|
|
40
40
|
|
|
41
41
|
- App is a Worker: code runs in a V8 isolate (web APIs, `nodejs_compat` flag for selected Node built-ins) — **not** full Node.
|
|
42
42
|
- Bindings are defined in an oblaka resource graph, directly in `oblaka.ts` or
|
|
43
|
-
through `
|
|
43
|
+
through `fabrika.config.ts` for a Fabrika-managed app; never hand-edit the generated
|
|
44
44
|
`wrangler.jsonc`.
|
|
45
45
|
- Local dev emulates D1/KV/R2/Queue/Cron (`lopata` or `wrangler dev`/workerd). **`analytics-engine` has no local runtime** (see `count-store`).
|
|
46
46
|
|
|
@@ -62,4 +62,4 @@ you compose, a stack you adopt.
|
|
|
62
62
|
|
|
63
63
|
- **requires `postgres`** — the entire schema/migration/ACL story is Postgres-specific (transitively excludes `d1`, same `relational-db` slot).
|
|
64
64
|
- **recommends `react` + `bindx`** — the admin UI and data binding are React; `bindx`/`@contember/react-binding` is the typed binding layer over its GraphQL API.
|
|
65
|
-
- **slot `backend`** — the backend choice (one backend per app). It also subsumes auth/identity, so it overlaps `auth-password-kv`/`
|
|
65
|
+
- **slot `backend`** — the backend choice (one backend per app). It also subsumes auth/identity, so it overlaps `auth-password-kv`/`fabrika-iam` conceptually — if Contember owns tenancy, don't double up.
|
|
@@ -1,49 +1,49 @@
|
|
|
1
1
|
---
|
|
2
|
-
id:
|
|
2
|
+
id: fabrika-control
|
|
3
3
|
kind: technology
|
|
4
|
-
title:
|
|
4
|
+
title: Fabrika Control — Cloudflare deploy control plane
|
|
5
5
|
slot: deploy-control-plane
|
|
6
6
|
provides: [deploy-control-plane, deployment, resource-provisioning, schema-reconciliation, secret-sync]
|
|
7
|
-
requires: [cloudflare, oblaka, wrangler,
|
|
7
|
+
requires: [cloudflare, oblaka, wrangler, fabrika-iam]
|
|
8
8
|
recommends: []
|
|
9
9
|
conflicts: []
|
|
10
|
-
npm: ["
|
|
10
|
+
npm: ["@fabrika/provider-cloudflare"]
|
|
11
11
|
status: wip
|
|
12
12
|
sources:
|
|
13
|
-
- where: "
|
|
13
|
+
- where: "the predecessor control-plane repository — README.md, MIGRATION.md, packages/config/src/, packages/core/src/{deploy,plan}.ts"
|
|
14
14
|
read: "The current defineApp contract, deploy plan order, per-app state namespace, single-account topology, registry and cut-over procedure."
|
|
15
|
-
- where: "
|
|
15
|
+
- where: "@fabrika/provider-cloudflare (installed source/types)"
|
|
16
16
|
read: "The exact AppConfig/ResourceContext/AppPipeline fields and re-exported oblaka primitives; this is 0.x, so do not infer fields from memory."
|
|
17
|
-
- where: "
|
|
18
|
-
read: "A full app config with a stable app id, ResourceContext,
|
|
17
|
+
- where: "the predecessor control-plane examples"
|
|
18
|
+
read: "A full app config with a stable app id, ResourceContext, Fabrika IAM schema, Worker resources, and pipeline secrets."
|
|
19
19
|
---
|
|
20
20
|
|
|
21
|
-
#
|
|
21
|
+
# Fabrika Control
|
|
22
22
|
|
|
23
23
|
## What it is
|
|
24
24
|
|
|
25
|
-
The deploy control plane for the Cloudflare +
|
|
26
|
-
`
|
|
25
|
+
The deploy control plane for the Cloudflare + Fabrika IAM ecosystem. An app owns one
|
|
26
|
+
`fabrika.config.ts` with `defineApp({ id, resources, schema?, pipeline? })`. Fabrika Control
|
|
27
27
|
clones the repository and executes the complete deployment in order: build,
|
|
28
|
-
resource provisioning through oblaka, D1 migrations, `wrangler deploy`,
|
|
28
|
+
resource provisioning through oblaka, D1 migrations, `wrangler deploy`, Fabrika IAM
|
|
29
29
|
schema reconciliation and Worker secret sync.
|
|
30
30
|
|
|
31
|
-
The app imports its deploy authoring surface from
|
|
31
|
+
The app imports its deploy authoring surface from **`@fabrika/provider-cloudflare` only**. That
|
|
32
32
|
package re-exports oblaka's `Worker`, `D1Database`, `R2Bucket`, `Queue`,
|
|
33
|
-
`ServiceReference`, etc., plus the
|
|
33
|
+
`ServiceReference`, etc., plus the Fabrika IAM schema types.
|
|
34
34
|
|
|
35
35
|
## When & why to use
|
|
36
36
|
|
|
37
|
-
- A production Cloudflare app in an account already managed by
|
|
37
|
+
- A production Cloudflare app in an account already managed by Fabrika Control + Fabrika IAM.
|
|
38
38
|
- You want repo config to declare resources, domain, authz vocabulary, build and
|
|
39
39
|
secrets while the control plane owns credentials, deploy locking and execution.
|
|
40
40
|
- You are replacing per-app GitHub Actions that separately run oblaka, migrations,
|
|
41
|
-
wrangler,
|
|
41
|
+
wrangler, Fabrika IAM provisioning and secret installation.
|
|
42
42
|
|
|
43
43
|
## When NOT to use
|
|
44
44
|
|
|
45
45
|
- The app is not deployed to Cloudflare.
|
|
46
|
-
- The target account has no
|
|
46
|
+
- The target account has no Fabrika Control plane. Bootstrapping Fabrika Control/Fabrika IAM for
|
|
47
47
|
an account is platform work, not an app scaffold step.
|
|
48
48
|
- A tiny experimental Worker intentionally deploys directly from a laptop or its
|
|
49
49
|
own workflow; use the direct `app-deploy` pattern instead.
|
|
@@ -51,8 +51,13 @@ package re-exports oblaka's `Worker`, `D1Database`, `R2Bucket`, `Queue`,
|
|
|
51
51
|
## App contract
|
|
52
52
|
|
|
53
53
|
```ts
|
|
54
|
-
import type { AppSchema, ResourceContext } from '
|
|
55
|
-
import {
|
|
54
|
+
import type { AppSchema, ResourceContext } from '@fabrika/provider-cloudflare'
|
|
55
|
+
import {
|
|
56
|
+
D1Database,
|
|
57
|
+
defineApp,
|
|
58
|
+
ServiceReference,
|
|
59
|
+
Worker,
|
|
60
|
+
} from '@fabrika/provider-cloudflare'
|
|
56
61
|
|
|
57
62
|
const APP_ID = 'example'
|
|
58
63
|
|
|
@@ -87,27 +92,27 @@ export default defineApp({
|
|
|
87
92
|
|
|
88
93
|
## Load-bearing gotchas
|
|
89
94
|
|
|
90
|
-
- **`id` is durable infrastructure identity.**
|
|
95
|
+
- **`id` is durable infrastructure identity.** Fabrika Control derives the default oblaka
|
|
91
96
|
state namespace as `<id>-state`. Never rename it casually. During migration it
|
|
92
97
|
must match the old namespace prefix or the first deploy can re-provision resources.
|
|
93
98
|
- **Use `ctx.domain`, not an app-specific hostname env var**, for the Worker custom
|
|
94
99
|
domain. The registry owns the domain per app environment.
|
|
95
|
-
- **One
|
|
96
|
-
account's independent
|
|
97
|
-
- **`schema` is deploy-time authz vocabulary; gates are not.** Native
|
|
100
|
+
- **One Fabrika Control per Cloudflare account.** A multi-account app is registered in each
|
|
101
|
+
account's independent Fabrika Control; the committed config remains account-neutral.
|
|
102
|
+
- **`schema` is deploy-time authz vocabulary; gates are not.** Native Fabrika IAM
|
|
98
103
|
`AppGates` live in Worker runtime code and are passed to `PropustkaAuth`.
|
|
99
104
|
Cloudflare Access declarations do not belong in a native-auth config.
|
|
100
|
-
- **Declare every required secret in `pipeline.secrets`.**
|
|
105
|
+
- **Declare every required secret in `pipeline.secrets`.** Fabrika Control resolves it from
|
|
101
106
|
the per-app/per-env vault and installs it. Do not add an independent
|
|
102
107
|
`wrangler secret put` workflow.
|
|
103
|
-
- **Verify installed
|
|
108
|
+
- **Verify installed `@fabrika/provider-cloudflare` types.** It is a 0.x package; fields such as
|
|
104
109
|
`pipeline.vars` may differ between the published package and repository head.
|
|
105
|
-
- **Do not hand-edit `wrangler.jsonc`.**
|
|
110
|
+
- **Do not hand-edit `wrangler.jsonc`.** Fabrika Control/oblaka materializes it before the
|
|
106
111
|
migration and deploy steps.
|
|
107
112
|
|
|
108
113
|
## Local development seam
|
|
109
114
|
|
|
110
|
-
|
|
115
|
+
Fabrika Control owns production deployment, not the local feedback loop. Export the resource
|
|
111
116
|
builder and reuse it from a thin `oblaka.ts` local shim where the installed APIs
|
|
112
117
|
permit it. Generate `wrangler.jsonc`, run the Worker with lopata, and run the SPA
|
|
113
118
|
with Vite. This keeps local binding definitions and production resources derived
|
|
@@ -115,8 +120,8 @@ from one graph instead of maintaining two copies.
|
|
|
115
120
|
|
|
116
121
|
## Relationships — why
|
|
117
122
|
|
|
118
|
-
- **requires `oblaka` + `wrangler`** —
|
|
123
|
+
- **requires `oblaka` + `wrangler`** — Fabrika Control provisions the resource graph with
|
|
119
124
|
oblaka, then invokes wrangler for D1 migrations, Worker deploy and secrets.
|
|
120
|
-
- **requires `
|
|
125
|
+
- **requires `fabrika-iam`** — the control plane is authenticated by Fabrika IAM and
|
|
121
126
|
reconciles an app's declared schema into it.
|
|
122
|
-
- **requires `cloudflare`** —
|
|
127
|
+
- **requires `cloudflare`** — Fabrika Control is a Cloudflare-specific deployment system.
|
|
@@ -1,35 +1,35 @@
|
|
|
1
1
|
---
|
|
2
|
-
id:
|
|
2
|
+
id: fabrika-iam
|
|
3
3
|
kind: technology
|
|
4
|
-
title:
|
|
4
|
+
title: Fabrika IAM — native login, authorization and audit
|
|
5
5
|
slot: authz
|
|
6
6
|
provides: [authentication, sso, authorization, audit, api-tokens]
|
|
7
7
|
requires: [cloudflare, d1]
|
|
8
|
-
recommends: [
|
|
8
|
+
recommends: [fabrika-control, buzola]
|
|
9
9
|
conflicts: [cloudflare-access, auth-password-kv]
|
|
10
10
|
npm: ["@propustka/client@^0.0.6", "@propustka/core@^0.0.6"]
|
|
11
11
|
status: wip
|
|
12
12
|
sources:
|
|
13
|
-
- where: "
|
|
13
|
+
- where: "the predecessor IAM repository — README.md, architecture.md, packages/core/src/, packages/worker/src/"
|
|
14
14
|
read: "Native session/login architecture, app gates, token/JWKS contract, central human identity and D1 policy/audit model."
|
|
15
15
|
- where: "@propustka/client (installed packages/client/src/{session,client,fake,types}.ts)"
|
|
16
16
|
read: "The current PropustkaAuth, AuthContext, AppGates, setCookie/loginUrl and FakeIamClient surfaces. Version 0.x moves quickly; read the source."
|
|
17
|
-
- where: "
|
|
17
|
+
- where: "the predecessor IAM examples"
|
|
18
18
|
read: "Runtime gates, local operator context, SSO redirects, response cookies, schemas, and IAM bindings."
|
|
19
19
|
---
|
|
20
20
|
|
|
21
|
-
#
|
|
21
|
+
# Fabrika IAM
|
|
22
22
|
|
|
23
23
|
## What it is
|
|
24
24
|
|
|
25
25
|
The native identity, authorization and audit service for Cloudflare Workers apps.
|
|
26
|
-
There is **no Cloudflare Access edge** in front of a native
|
|
27
|
-
|
|
26
|
+
There is **no Cloudflare Access edge** in front of a native Fabrika IAM app.
|
|
27
|
+
Fabrika IAM owns human SSO sessions, per-app permission tokens, `px_` service keys,
|
|
28
28
|
authorization policy and audit logs.
|
|
29
29
|
|
|
30
30
|
An app integrates over an `IAM` Worker-to-Worker service binding and uses
|
|
31
31
|
`PropustkaAuth` as its single request-auth seam. `PropustkaAuth` applies ordered
|
|
32
|
-
per-path gates, verifies cached permission JWTs locally against
|
|
32
|
+
per-path gates, verifies cached permission JWTs locally against Fabrika IAM's JWKS,
|
|
33
33
|
and only calls the binding when it must exchange a session/key or write audit.
|
|
34
34
|
|
|
35
35
|
## When & why to use
|
|
@@ -38,7 +38,7 @@ and only calls the binding when it must exchange a session/key or write audit.
|
|
|
38
38
|
- The same API supports logged-in people and `px_` service credentials.
|
|
39
39
|
- You want a central people directory, app-defined roles/scopes, revocable keys
|
|
40
40
|
and an audit trail.
|
|
41
|
-
- The target Cloudflare account already runs
|
|
41
|
+
- The target Cloudflare account already runs Fabrika IAM (normally alongside Fabrika Control).
|
|
42
42
|
|
|
43
43
|
## When NOT to use
|
|
44
44
|
|
|
@@ -46,7 +46,7 @@ and only calls the binding when it must exchange a session/key or write audit.
|
|
|
46
46
|
- There are no real authz/audit needs and a central IAM dependency is unjustified.
|
|
47
47
|
- The product requires app-owned signup/password recovery; use a product auth
|
|
48
48
|
system instead.
|
|
49
|
-
- Strict hierarchical scopes are fundamental.
|
|
49
|
+
- Strict hierarchical scopes are fundamental. Fabrika IAM scope dimensions are
|
|
50
50
|
flat; containment must be resolved by the app.
|
|
51
51
|
|
|
52
52
|
## Runtime integration
|
|
@@ -105,13 +105,13 @@ can make login appear broken.
|
|
|
105
105
|
## Authorization model
|
|
106
106
|
|
|
107
107
|
- Keep action ids, scope dimensions and the app id as shared constants. Runtime
|
|
108
|
-
`can()` checks and
|
|
108
|
+
`can()` checks and Fabrika Control's `AppSchema` must use the same vocabulary.
|
|
109
109
|
- `can(action, scope?)` and `scopedTo(action, dimension)` are local pure checks on
|
|
110
110
|
the minted permission set. `scopedTo` returns `null` (all), `[]` (none), or an
|
|
111
111
|
exact list.
|
|
112
112
|
- Audit is the operation that reaches the binding on the hot path; schedule it
|
|
113
113
|
with `ctx.waitUntil`.
|
|
114
|
-
- The app's `schema` (actions/scopes/roles) is reconciled by
|
|
114
|
+
- The app's `schema` (actions/scopes/roles) is reconciled by Fabrika Control during deploy.
|
|
115
115
|
|
|
116
116
|
## Local development and opice
|
|
117
117
|
|
|
@@ -127,11 +127,11 @@ local runtime cannot resolve it. Off-local, fail loudly if `IAM` or
|
|
|
127
127
|
## Relationships — why
|
|
128
128
|
|
|
129
129
|
- **requires `cloudflare`** — request auth and audit use a Worker service binding.
|
|
130
|
-
- **requires `d1`** — the separately deployed
|
|
130
|
+
- **requires `d1`** — the separately deployed Fabrika IAM service stores identity,
|
|
131
131
|
policy, sessions and audit data in D1.
|
|
132
|
-
- **conflicts `cloudflare-access`** — native
|
|
132
|
+
- **conflicts `cloudflare-access`** — native Fabrika IAM replaces the Access edge;
|
|
133
133
|
combining both creates two competing login/gate systems.
|
|
134
|
-
- **conflicts `auth-password-kv`** —
|
|
134
|
+
- **conflicts `auth-password-kv`** — Fabrika IAM owns login and sessions; do not add
|
|
135
135
|
a parallel app-owned password session.
|
|
136
|
-
- **recommends `
|
|
136
|
+
- **recommends `fabrika-control`** for schema reconciliation and **`buzola`** for internal
|
|
137
137
|
app SPAs.
|