@fabrika/provider-zerops 0.9.0-dev.13 → 0.9.0-dev.14

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fabrika/provider-zerops",
3
- "version": "0.9.0-dev.13",
3
+ "version": "0.9.0-dev.14",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",
@@ -45,15 +45,15 @@
45
45
  },
46
46
  "dependencies": {
47
47
  "zod": "^3.25.76",
48
- "@fabrika/app": "0.9.0-dev.13",
49
- "@fabrika/auth": "0.9.0-dev.13",
50
- "@fabrika/auth-core": "0.9.0-dev.13",
51
- "@fabrika/email": "0.9.0-dev.13",
52
- "@fabrika/iam-contract": "0.9.0-dev.13",
53
- "@fabrika/installation-init": "0.9.0-dev.13",
54
- "@fabrika/operations-contract": "0.9.0-dev.13",
55
- "@fabrika/provider-contract": "0.9.0-dev.13",
56
- "@fabrika/proxy-core": "0.9.0-dev.13",
48
+ "@fabrika/app": "0.9.0-dev.14",
49
+ "@fabrika/auth": "0.9.0-dev.14",
50
+ "@fabrika/auth-core": "0.9.0-dev.14",
51
+ "@fabrika/email": "0.9.0-dev.14",
52
+ "@fabrika/iam-contract": "0.9.0-dev.14",
53
+ "@fabrika/installation-init": "0.9.0-dev.14",
54
+ "@fabrika/operations-contract": "0.9.0-dev.14",
55
+ "@fabrika/provider-contract": "0.9.0-dev.14",
56
+ "@fabrika/proxy-core": "0.9.0-dev.14",
57
57
  "yaml": "^2.9.1"
58
58
  }
59
59
  }
package/src/api/client.ts CHANGED
@@ -6,6 +6,8 @@ import {
6
6
  appVersionListSchema,
7
7
  appVersionSchema,
8
8
  backupConfigSchema,
9
+ backupFilesSchema,
10
+ backupStartSchema,
9
11
  importResultSchema,
10
12
  integrationTokenSchema,
11
13
  logAccessSchema,
@@ -382,6 +384,12 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
382
384
  return readResponse('configure backup', processNilSchema, payload).process ?? null
383
385
  },
384
386
 
387
+ createBackup: async ({ serviceId, tags, signal }) =>
388
+ readResponse('back up', backupStartSchema, await request('back up', 'POST', `/service-stack/${serviceId}/backup`, { body: { tags }, signal })),
389
+
390
+ listBackups: async ({ serviceId, signal }) =>
391
+ readResponse('list backups', backupFilesSchema, await request('list backups', 'GET', `/service-stack/${serviceId}/backup`, { signal })),
392
+
385
393
  getService: async ({ serviceId, signal }) =>
386
394
  readResponse('get service', serviceSchema, await request('get service', 'GET', `/service-stack/${serviceId}`, { signal })),
387
395
 
@@ -4,7 +4,9 @@ import type {
4
4
  ZeropsAppVersion,
5
5
  ZeropsAppVersionStatus,
6
6
  ZeropsBackupConfig,
7
+ ZeropsBackupFile,
7
8
  ZeropsBackupRetentionPolicy,
9
+ ZeropsBackupStart,
8
10
  ZeropsImportResult,
9
11
  ZeropsIntegrationToken,
10
12
  ZeropsLogAccess,
@@ -199,6 +201,16 @@ export const backupConfigSchema = z.object({
199
201
  ...(retentionPolicy === null || retentionPolicy === undefined ? {} : { retentionPolicy }),
200
202
  }))
201
203
 
204
+ /** A file whose tags do not parse has none: a backup is looked for by its tag, so it is never taken for one. */
205
+ const backupFileSchema = z.object({
206
+ name: z.string(),
207
+ metadata: z.object({ tags: z.array(z.string()).catch([]).optional() }).nullish().catch(null),
208
+ }).transform(({ name, metadata }): ZeropsBackupFile => ({ name, tags: metadata?.tags ?? [] }))
209
+
210
+ export const backupFilesSchema = z.object({ files: z.array(backupFileSchema).nullable() }).transform(({ files }) => files ?? [])
211
+
212
+ export const backupStartSchema = z.object({ success: z.boolean(), async: z.boolean() }) satisfies z.ZodType<ZeropsBackupStart, z.ZodTypeDef, unknown>
213
+
202
214
  export const projectSchema = z.object({
203
215
  id: idSchema,
204
216
  name: z.string(),
package/src/api/types.ts CHANGED
@@ -224,6 +224,25 @@ export interface ZeropsBackupConfig {
224
224
  retentionPolicy?: ZeropsBackupRetentionPolicy
225
225
  }
226
226
 
227
+ /**
228
+ * One stored backup of a managed service: `OutDtoServiceStackBackupFile`, narrowed to its `name` and the `tags` of its
229
+ * `metadata`. Verified live 2026-11-17: `metadata.tags` is a JSON array of strings, and the metadata keys are snake_case
230
+ * (`file_name`, `stack_name`), not the documented `filename` and `stackname`.
231
+ */
232
+ export interface ZeropsBackupFile {
233
+ /** The moment the backup was taken, as the platform names the file. */
234
+ name: string
235
+ tags: string[]
236
+ }
237
+
238
+ /** What a backup request answers. VERIFIED AS A SHAPE: `ResponseServiceStackBackup`. */
239
+ export interface ZeropsBackupStart {
240
+ /** The backup was started, and is finished or running in the background. */
241
+ success: boolean
242
+ /** It ran past the platform's 10 s window and goes on in the background; `false` answers a finished backup. */
243
+ async: boolean
244
+ }
245
+
227
246
  /** One service. VERIFIED: `ResponseServiceStack` (narrowed to the fields fabrika reads). */
228
247
  export interface ZeropsService {
229
248
  id: string
@@ -558,6 +577,20 @@ export interface ZeropsApi {
558
577
  signal: AbortSignal
559
578
  }): Promise<ZeropsProcess | null>
560
579
 
580
+ /**
581
+ * Back a managed service up now, under `tags`. VERIFIED AS A SHAPE: `POST /service-stack/{id}/backup`
582
+ * (`BackupServiceStack`), body `RequestPostServiceStackBackup`, response `ResponseServiceStackBackup`. It names no
583
+ * process. Verified live 2026-11-17: `async: false` answers a finished backup, listed at once; a user tag outside 1–24
584
+ * characters of `[A-Za-z0-9:_-]` is 400 `backupTagNameFormat`.
585
+ */
586
+ createBackup(input: { serviceId: string; tags: string[]; signal: AbortSignal }): Promise<ZeropsBackupStart>
587
+
588
+ /**
589
+ * The stored backups of a managed service. VERIFIED AS A SHAPE: the `files` of `GET /service-stack/{id}/backup`
590
+ * (`ListBackups`). UNVERIFIED: whether a backup still running (`async: true`) is listed before it completes.
591
+ */
592
+ listBackups(input: { serviceId: string; signal: AbortSignal }): Promise<ZeropsBackupFile[]>
593
+
561
594
  // ── service-stack / project: reading state ────────────────────────────────────
562
595
 
563
596
  /** One service by id. VERIFIED: `GET /service-stack/{id}`. */
package/src/api.ts CHANGED
@@ -20,7 +20,9 @@ export {
20
20
  type ZeropsAppVersionStatus,
21
21
  type ZeropsAppVersionUpload,
22
22
  type ZeropsBackupConfig,
23
+ type ZeropsBackupFile,
23
24
  type ZeropsBackupRetentionPolicy,
25
+ type ZeropsBackupStart,
24
26
  type ZeropsImportedService,
25
27
  type ZeropsImportResult,
26
28
  type ZeropsIntegrationToken,
@@ -0,0 +1,117 @@
1
+ // Whether the Bun of a contract application's build base reads its `bun.lock`. The platform build installs with
2
+ // `bun install --frozen-lockfile` on the base the selected setup names in `build.base` (ADR-0043), and a Bun older than
3
+ // the one that wrote the lockfile fails that install late, in a started build container, with `Unknown lockfile
4
+ // version`. `fabrika app build`, `app register` and the builder's deploy refuse such a base before anything deploys,
5
+ // from the lockfile they compile beside; a commit after registration is not checked. PURE: no filesystem.
6
+
7
+ import type { JsonValue } from '@fabrika/provider-contract'
8
+ import { parseZeropsDescriptor, selectZeropsDescriptorSetup } from './descriptor'
9
+ import { lockedAuthoredBuild, ZEROPS_APPLICATION_RUNTIME } from './execution'
10
+ import type { FabrikaManifest } from './manifest'
11
+
12
+ interface BunRelease {
13
+ readonly major: number
14
+ readonly minor: number
15
+ }
16
+
17
+ /**
18
+ * The oldest Bun that reads each `lockfileVersion` of a text `bun.lock` (measured: 1.1.45 reads 0 and refuses 1, 1.2
19
+ * and 1.3 read 1 and refuse 2, 1.4 writes 2 for a new lockfile). A version missing here is newer than every Bun this
20
+ * list knows. Add a row when a Bun release writes a new version.
21
+ */
22
+ const LOCKFILE_READERS: ReadonlyMap<number, BunRelease> = new Map([
23
+ [0, { major: 1, minor: 1 }],
24
+ [1, { major: 1, minor: 2 }],
25
+ [2, { major: 1, minor: 4 }],
26
+ ])
27
+
28
+ /** The oldest Bun base Zerops offers (`alpine/bun@1.3`, `ubuntu/bun@1.3`): a refusal never names an older one. */
29
+ const OLDEST_OFFERED_BUN: BunRelease = { major: 1, minor: 3 }
30
+
31
+ /** The newest Bun the table knows: it writes the newest `lockfileVersion` there, and reads no newer one. */
32
+ const NEWEST_KNOWN_BUN: BunRelease = { major: 1, minor: 4 }
33
+ const NEWEST_KNOWN_LOCKFILE = Math.max(...LOCKFILE_READERS.keys())
34
+
35
+ /** A Bun base with a numeric version: `bun@1.3`, `alpine/bun@1.3`, `ubuntu/bun@1.3.9`. An alias such as `@latest` is not. */
36
+ const BUN_BASE = /^((?:alpine|ubuntu)\/)?bun@(\d+)\.(\d+)(?:\.\d+)?$/
37
+
38
+ const atLeast = (release: BunRelease, floor: BunRelease): boolean =>
39
+ release.major > floor.major || (release.major === floor.major && release.minor >= floor.minor)
40
+
41
+ const named = (release: BunRelease): string => `${release.major}.${release.minor}`
42
+
43
+ /**
44
+ * The `lockfileVersion` of a `bun.lock`, or null when the text does not start with one. Bun writes it as the first
45
+ * key; the rest of the file is JSONC (trailing commas), which this never parses.
46
+ */
47
+ export function bunLockfileVersion(text: string): number | null {
48
+ const unmarked = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text
49
+ const match = /^\s*\{\s*"lockfileVersion"\s*:\s*(\d+)\s*[,}]/.exec(unmarked)
50
+ return match?.[1] === undefined ? null : Number(match[1])
51
+ }
52
+
53
+ /** The build base of the manifest's selected setup, and whether the application named it or the platform's default applies. */
54
+ export interface ZeropsBuildBase {
55
+ readonly setup: string
56
+ /** Each base the build image is made of; empty for an application without a contract, whose build is its own. */
57
+ readonly bases: readonly string[]
58
+ readonly authored: boolean
59
+ }
60
+
61
+ const isSetup = (value: JsonValue, setup: string): value is { readonly [key: string]: JsonValue } =>
62
+ typeof value === 'object' && value !== null && !Array.isArray(value) && value['setup'] === setup
63
+
64
+ /**
65
+ * The bases the platform build of a contract application runs on, read as `renderLockedSetup` reads them: the selected
66
+ * setup's `build.base`, or the platform's runtime when it names none. The platform does not generate the build of an
67
+ * application without a contract, so it has none here.
68
+ */
69
+ export function zeropsBuildBase(manifest: FabrikaManifest): ZeropsBuildBase {
70
+ const parsed = parseZeropsDescriptor(manifest.target.sourceDescriptor.contents)
71
+ const setup = selectZeropsDescriptorSetup(parsed, manifest.target.zeropsSetup)
72
+ const entries = parsed.document['zerops']
73
+ const entry = Array.isArray(entries) ? entries.find((candidate) => isSetup(candidate, setup)) : undefined
74
+ if (manifest.target.contract === undefined || entry === undefined) return { setup, bases: [], authored: false }
75
+ const base = lockedAuthoredBuild(entry, setup).base
76
+ if (base === null) return { setup, bases: [ZEROPS_APPLICATION_RUNTIME], authored: false }
77
+ return { setup, bases: typeof base === 'string' ? [base] : base, authored: true }
78
+ }
79
+
80
+ /**
81
+ * Why the build cannot install from a `bun.lock` of this text, or null when it can or when that cannot be known: a
82
+ * lockfile without a readable version, or a base that is not a Bun release with a numeric version (an alias such as
83
+ * `alpine/bun@latest`, or another runtime).
84
+ */
85
+ export function buildBaseLockfileRefusal(lockfile: string, build: ZeropsBuildBase): string | null {
86
+ const version = bunLockfileVersion(lockfile)
87
+ if (version === null) return null
88
+ const reader = LOCKFILE_READERS.get(version)
89
+ for (const base of build.bases) {
90
+ const match = BUN_BASE.exec(base)
91
+ if (match === null) continue
92
+ const bun = { major: Number(match[2]), minor: Number(match[3]) }
93
+ const where = build.authored
94
+ ? `build.base \`${base}\` of zerops.yaml setup \`${build.setup}\``
95
+ : `\`${base}\`, the base of zerops.yaml setup \`${build.setup}\`, which names no build.base`
96
+ const install = `the platform build runs \`bun install --frozen-lockfile\` on ${where}`
97
+ if (reader === undefined) {
98
+ // A Bun newer than every known one may read it; only a known one is refused.
99
+ if (atLeast(NEWEST_KNOWN_BUN, bun)) {
100
+ const known = `Bun ${named(NEWEST_KNOWN_BUN)} reads up to lockfileVersion ${NEWEST_KNOWN_LOCKFILE}`
101
+ return `bun.lock has lockfileVersion ${version}, newer than any Bun base this release knows (${known}), and ${install}; set build.base to the Bun release that wrote bun.lock (\`bun --version\`)`
102
+ }
103
+ continue
104
+ }
105
+ if (!atLeast(bun, reader)) {
106
+ const remedy = `${match[1] ?? ''}bun@${named(atLeast(reader, OLDEST_OFFERED_BUN) ? reader : OLDEST_OFFERED_BUN)}`
107
+ return `bun.lock has lockfileVersion ${version}, which Bun ${
108
+ named(bun)
109
+ } cannot read, and ${install}; set build.base: ${remedy}, or regenerate bun.lock with Bun ${named(bun)}, which resolves every dependency afresh`
110
+ }
111
+ }
112
+ return null
113
+ }
114
+
115
+ /** Why the manifest's build cannot install from a `bun.lock` of this text, or null; what every compile runs. */
116
+ export const lockfileBuildBaseRefusal = (manifest: FabrikaManifest, lockfile: string): string | null =>
117
+ buildBaseLockfileRefusal(lockfile, zeropsBuildBase(manifest))
package/src/cli.ts CHANGED
@@ -5,6 +5,7 @@ import { open } from 'node:fs/promises'
5
5
  import { resolve } from 'node:path'
6
6
  import { z } from 'zod'
7
7
  import { isZeropsAppConfig } from './authoring'
8
+ import { lockfileBuildBaseRefusal } from './build-base'
8
9
  import { parseZeropsCliArgs } from './cli-args'
9
10
  import {
10
11
  compileFabrikaManifest,
@@ -78,17 +79,31 @@ export interface ZeropsManifestBuildOptions {
78
79
  readonly env: string
79
80
  }
80
81
 
81
- const compileManifest = async (options: ZeropsManifestBuildOptions): Promise<FabrikaManifest> => {
82
+ /**
83
+ * Refuse a build base whose Bun cannot read the repository-root `bun.lock`, which the platform build installs from with
84
+ * `--frozen-lockfile`. Without a `bun.lock` there is nothing to compare; Control refuses a commit without one. `command`
85
+ * names what ran, as the refusal's prefix.
86
+ */
87
+ export const assertBuildBaseReadsLockfile = async (manifest: FabrikaManifest, command: string, root: string = process.cwd()): Promise<void> => {
88
+ const lockfile = Bun.file(resolve(root, 'bun.lock'))
89
+ if (!(await lockfile.exists())) return
90
+ const refusal = lockfileBuildBaseRefusal(manifest, await lockfile.text())
91
+ if (refusal !== null) throw new Error(`${command}: ${refusal}`)
92
+ }
93
+
94
+ const compileManifest = async (options: ZeropsManifestBuildOptions, command: string): Promise<FabrikaManifest> => {
82
95
  const config = await loadConfig(options.config)
83
96
  const sourceDescriptor = await readZeropsSourceDescriptor()
84
- return compileFabrikaManifest(config, options.env, sourceDescriptor)
97
+ const manifest = compileFabrikaManifest(config, options.env, sourceDescriptor)
98
+ await assertBuildBaseReadsLockfile(manifest, command)
99
+ return manifest
85
100
  }
86
101
 
87
102
  const serializeManifest = (manifest: FabrikaManifest): string => `${JSON.stringify(manifest, null, '\t')}\n`
88
103
 
89
- /** The exact text `build` writes to `fabrika.manifest.json`, produced in memory and written nowhere. */
104
+ /** The exact text `build` writes to `fabrika.manifest.json`, produced in memory and written nowhere: what `app register` sends. */
90
105
  export const buildZeropsManifestText = async (options: ZeropsManifestBuildOptions): Promise<string> =>
91
- serializeManifest(await compileManifest(options))
106
+ serializeManifest(await compileManifest(options, 'fabrika app register'))
92
107
 
93
108
  export const runZeropsCli = async (argv: readonly string[]): Promise<void> => {
94
109
  const args = parseZeropsCliArgs(argv)
@@ -102,7 +117,7 @@ export const runZeropsCli = async (argv: readonly string[]): Promise<void> => {
102
117
  if (args.env === undefined || args.env === '') {
103
118
  throw new Error('`build` requires --env=<env>')
104
119
  }
105
- const manifest = await compileManifest({ config: args.config, env: args.env })
120
+ const manifest = await compileManifest({ config: args.config, env: args.env }, 'fabrika app build')
106
121
  const output = resolve(process.cwd(), args.output)
107
122
  await Bun.write(output, serializeManifest(manifest))
108
123
  console.info(`wrote ${output} (${manifestServiceHostnames(manifest).length} service(s))`)
@@ -5,6 +5,15 @@ import type { ZeropsRuntimeTarget } from './types'
5
5
 
6
6
  export type Sleeper = (ms: number, signal: AbortSignal) => Promise<void>
7
7
 
8
+ /** Elapsed time and the per-request timeouts measured on it. */
9
+ export interface ZeropsClock {
10
+ now(): number
11
+ /** A signal that aborts `ms` from now. */
12
+ timeout(ms: number): AbortSignal
13
+ }
14
+
15
+ export const systemClock: ZeropsClock = { now: () => Date.now(), timeout: (ms) => AbortSignal.timeout(ms) }
16
+
8
17
  export const defaultSleep: Sleeper = (ms, signal) =>
9
18
  new Promise<void>((resolve) => {
10
19
  if (signal.aborted) {
@@ -29,6 +38,8 @@ export interface ZeropsCollaborators {
29
38
  /** Raises the Operations alert for a refused activation; best-effort. */
30
39
  alertExposure: ExposureAlerter
31
40
  sleep: Sleeper
41
+ /** The clock the database backup's wait runs on; the system clock when absent. */
42
+ clock?: ZeropsClock
32
43
  }
33
44
 
34
45
  export type ZeropsCollaboratorFactory = (target: ZeropsRuntimeTarget) => ZeropsCollaborators
package/src/control.ts CHANGED
@@ -475,6 +475,9 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
475
475
  artifact,
476
476
  ...(input.environment.access === undefined ? {} : { access: input.environment.access }),
477
477
  ...(input.artifactUpload === undefined ? {} : { artifactUpload: input.artifactUpload }),
478
+ ...(input.backupBeforeMigrations === undefined
479
+ ? {}
480
+ : { backupBeforeMigrations: { migrations: input.backupBeforeMigrations.migrations, runId: input.runId } }),
478
481
  dryRun: input.dryRun,
479
482
  signal: input.signal,
480
483
  events: input.events,
package/src/index.ts CHANGED
@@ -40,6 +40,7 @@ export type {
40
40
  } from './api'
41
41
  export { defineApp, isZeropsAppConfig, useSharedPostgres, zeropsSharedServiceHostname, zeropsSharedServicePrefix } from './authoring'
42
42
  export type { ZeropsAuthoredAppConfig } from './authoring'
43
+ export { lockfileBuildBaseRefusal } from './build-base'
43
44
  export { parseZeropsCliArgs } from './cli-args'
44
45
  export type { ZeropsCliArgs } from './cli-args'
45
46
  export { defaultSleep, defaultZeropsCollaborators } from './collaborators'
@@ -96,7 +96,7 @@ const report = (result: FirstAdministratorResult, log: AdminLog): void => {
96
96
  * The one place the enrollment URL is ever written, and it is written once.
97
97
  *
98
98
  * A URL that sets a password is a credential: it goes to stdout on a line of its own, is stored
99
- * nowhere, and is not repeated. The three other outcomes carry no URL at all and say what was found.
99
+ * nowhere, and is not repeated. The other outcomes carry no URL at all and say what was found.
100
100
  */
101
101
  const announceEnrollment = (result: FirstAdministratorResult, log: AdminLog, print: (line: string) => void): void => {
102
102
  if (result.enrollment.state === 'already-set') {
@@ -104,6 +104,11 @@ const announceEnrollment = (result: FirstAdministratorResult, log: AdminLog, pri
104
104
  log.info('Sign in at the console. A forgotten password is a reset, which the Access plane issues to a signed-in administrator.')
105
105
  return
106
106
  }
107
+ if (result.enrollment.state === 'single-sign-on') {
108
+ log.ok('this installation offers no password, so no enrollment was issued')
109
+ log.info(`Sign in at the console with single sign-on as ${result.email}: the identity provider must vouch for that address.`)
110
+ return
111
+ }
107
112
  if (result.enrollment.state === 'outstanding') {
108
113
  log.warn(`an enrollment is already outstanding — a second one was NOT issued. Pass ${REISSUE_FLAG} to replace it if the first expired unopened`)
109
114
  return
@@ -308,6 +308,46 @@ export const PLATFORM_PROXY_MANIFEST_TEMPLATE: PlatformProxyManifestTemplate = {
308
308
  admission: null,
309
309
  oauth: null,
310
310
  },
311
+ {
312
+ id: 'github-handoff',
313
+ kind: 'protocol',
314
+ method: 'GET',
315
+ path: '/api/source/github/handoff/:connectionId',
316
+ callers: [],
317
+ requirement: null,
318
+ admission: null,
319
+ oauth: null,
320
+ },
321
+ {
322
+ id: 'github-handoff-open',
323
+ kind: 'protocol',
324
+ method: 'POST',
325
+ path: '/api/source/github/handoff/:connectionId',
326
+ callers: [],
327
+ requirement: null,
328
+ admission: null,
329
+ oauth: null,
330
+ },
331
+ {
332
+ id: 'github-handoff-callback',
333
+ kind: 'protocol',
334
+ method: 'GET',
335
+ path: '/api/source/github/handoff-callback',
336
+ callers: [],
337
+ requirement: null,
338
+ admission: null,
339
+ oauth: null,
340
+ },
341
+ {
342
+ id: 'github-handoff-setup',
343
+ kind: 'protocol',
344
+ method: 'GET',
345
+ path: '/api/source/github/handoff-setup/:connectionId',
346
+ callers: [],
347
+ requirement: null,
348
+ admission: null,
349
+ oauth: null,
350
+ },
311
351
  {
312
352
  id: 'rpc',
313
353
  kind: 'service',
@@ -513,6 +553,46 @@ export const PLATFORM_PROXY_MANIFEST_TEMPLATE: PlatformProxyManifestTemplate = {
513
553
  admission: null,
514
554
  oauth: null,
515
555
  },
556
+ {
557
+ id: 'github-handoff',
558
+ kind: 'protocol',
559
+ method: 'GET',
560
+ path: '/api/source/github/handoff/:connectionId',
561
+ callers: [],
562
+ requirement: null,
563
+ admission: null,
564
+ oauth: null,
565
+ },
566
+ {
567
+ id: 'github-handoff-open',
568
+ kind: 'protocol',
569
+ method: 'POST',
570
+ path: '/api/source/github/handoff/:connectionId',
571
+ callers: [],
572
+ requirement: null,
573
+ admission: null,
574
+ oauth: null,
575
+ },
576
+ {
577
+ id: 'github-handoff-callback',
578
+ kind: 'protocol',
579
+ method: 'GET',
580
+ path: '/api/source/github/handoff-callback',
581
+ callers: [],
582
+ requirement: null,
583
+ admission: null,
584
+ oauth: null,
585
+ },
586
+ {
587
+ id: 'github-handoff-setup',
588
+ kind: 'protocol',
589
+ method: 'GET',
590
+ path: '/api/source/github/handoff-setup/:connectionId',
591
+ callers: [],
592
+ requirement: null,
593
+ admission: null,
594
+ oauth: null,
595
+ },
516
596
  {
517
597
  id: 'rpc',
518
598
  kind: 'service',
@@ -16,15 +16,19 @@ message that names the flag or the variable to set. Read the message: it names t
16
16
 
17
17
  **Ask the human for these first.** You cannot produce them, and each one blocks a later step:
18
18
 
19
- | What | Needed at |
20
- | ------------------------------------------------------------------------------------- | ---------- |
21
- | A Zerops PERSONAL access token of a client OWNER, generated in the Zerops GUI | step 1 |
22
- | A verified Zerops account (credit topped up once); an unverified one owns ONE project | step 5 |
23
- | A `gh` login allowed to create a repository in the organization that owns it | step 3 |
24
- | The administrator's e-mail address, and the human to open the enrollment URL | step 2 |
25
- | For a PRIVATE application repository: the GitHub App connected in the console | step 5 |
26
- | The fabrika release tag to install, for example `v0.4.3` (a branch is refused) | steps 1, 3 |
27
- | The four decisions below | steps 1, 5 |
19
+ | What | Needed at |
20
+ | ---------------------------------------------------------------------------------------- | ---------- |
21
+ | A Zerops PERSONAL access token of a client OWNER, generated in the Zerops GUI | step 1 |
22
+ | A verified Zerops account (credit topped up once); an unverified one owns ONE project | step 5 |
23
+ | A `gh` login allowed to create a repository in the organization that owns it | step 3 |
24
+ | The administrator's e-mail address, and the human to open the enrollment URL | step 2 |
25
+ | For a PRIVATE application repository: the GitHub App connected in the console | step 5 |
26
+ | The fabrika release tag to install, for example `v0.4.3` (a branch is refused) | steps 1, 3 |
27
+ | The five decisions below | steps 1, 5 |
28
+ | Single sign-on only: the identity provider's issuer, client id and secret, and its admin | steps 1, 2 |
29
+
30
+ The identity provider's admin is whoever can register the redirect URI that step 1 prints at its end; single sign-on
31
+ fails until it is registered.
28
32
 
29
33
  Every namespace is a Zerops project of its own, so the first one fails with `clientProjectCountLimitExceededTopUp`
30
34
  on an unverified account (observed 2026-10-15).
@@ -95,6 +99,12 @@ container (a deploy raises the floor of an application with a database to 0.5 GB
95
99
  every environment. `SERIOUS` adds $10 per namespace and a highly available balancer in front of its proxy,
96
100
  and it can never be downgraded again.
97
101
 
102
+ **5. Sign-in method** (`platform install --auth-methods`, step 1). Free either way. `password` (the default)
103
+ needs nothing else: each person sets a password from an enrollment link. `oidc,password` adds single sign-on through
104
+ the organization's OpenID Connect identity provider beside it, and `oidc` alone removes passwords. Single sign-on
105
+ needs the provider's client (see Before you start). Who it admits is step 4 of "Turn on single sign-on" below,
106
+ which also turns it on or off later by hand.
107
+
98
108
  ## Secrets: rules for an agent
99
109
 
100
110
  - Every credential is read from the ENVIRONMENT ONLY. No command takes one as a flag.
@@ -156,6 +166,13 @@ fabrika platform install --provider=zerops --create-project --client-id=<clientI
156
166
  provider's variables from their own `0600` files. `fabrika platform install --provider=zerops --help` lists the
157
167
  providers and their variables, each named after its provider (for Resend `FABRIKA_EMAIL_RESEND_API_KEY`). They have no flag. The install writes the set on `iam` and `control`, the credentials sensitive. They
158
168
  are the human's own, so they are not copied into the secrets file.
169
+ - Sign-in is password only unless `--auth-methods` says otherwise. For single sign-on from the start, add
170
+ `--auth-methods=oidc,password --oidc-issuer=<issuer URL> --oidc-client-id=<client id>` and export
171
+ `FABRIKA_IAM_OIDC_CLIENT_SECRET` from its own `0600` file; it has no flag. The install writes the client on `iam`,
172
+ the secret sensitive and not into the secrets file. The IAM host exists only once pass 1 has run, so the log
173
+ ends with a `REGISTER THE REDIRECT URI` box: register that URI at the identity provider. `--auth-methods=oidc`
174
+ turns password sign-in off, and step 2 then admits the administrator without an enrollment. To add single sign-on later, see
175
+ "Turn on single sign-on" below.
159
176
 
160
177
  **Check.** The log ends with the `Hand off` step: where the credentials are, `The console answers at
161
178
  https://<console host>`, and an `ADMIT YOURSELF` box that holds the step 2 command with `--iam-host` filled
@@ -172,7 +189,9 @@ in. The secrets file exists with mode `0600`. The three hosts are printed earlie
172
189
  Without a mail provider it prints one enrollment URL and the time it expires. Nothing is e-mailed then, so
173
190
  do not tell the human to wait for a message. The URL is a credential: give it to the human only, and do not
174
191
  log it. The human opens it, sets a password and signs in at the console origin. With a mail provider, IAM
175
- e-mails the enrollment instead, and the command reports the address and the expiry.
192
+ e-mails the enrollment instead, and the command reports the address and the expiry. On an installation without
193
+ passwords (`--auth-methods=oidc`) it issues no enrollment: it reports that the administrator signs in with single
194
+ sign-on and exits 0. The identity provider must vouch for the same e-mail address.
176
195
 
177
196
  The URL is valid for ONE HOUR. Hand it over at once. A re-run creates nothing new: while the enrollment is
178
197
  unused it only reports that one is outstanding, and it never prints the URL again. To get a new URL, after
@@ -267,6 +286,17 @@ included, is the tag's version: `bun pm ls --all | grep @fabrika/`. Releases up
267
286
  `@fabrika/*` dependencies by a range, so a transitive one can still resolve a later patch of that line. Then
268
287
  install the newest patch instead (step 6 upgrades an installation).
269
288
 
289
+ **Build on a Bun that reads `bun.lock`.** The platform build runs `bun install --frozen-lockfile` on the
290
+ `build.base` of the application's `zerops.yaml` (`alpine/bun@1.3` when it names none), and an older Bun cannot
291
+ read a newer lockfile. A `bun.lock` that Bun 1.4 creates or regenerates has `"lockfileVersion": 2` (Bun 1.4 keeps
292
+ an existing version 1 lockfile at 1), which Bun 1.3 refuses, so the build fails with
293
+ `Unknown lockfile version ... lockfile is frozen`. Read the version with `head -2 bun.lock`. Versions 0 and 1 build
294
+ on `alpine/bun@1.3`, the oldest Bun base Zerops offers; version 2 needs `alpine/bun@1.4` or later. Raise
295
+ `build.base` to `alpine/bun@1.4`, or regenerate `bun.lock` with the base's Bun (delete it and run `bun install` with
296
+ Bun 1.3), which resolves every dependency afresh. `fabrika app build` and `app register` refuse a base that cannot
297
+ read the lockfile and name the one to use. They read the `bun.lock` beside them when they run: a lockfile
298
+ regenerated after registration is not checked, and only the build itself fails on it.
299
+
270
300
  1. **Create a namespace** with the preset and core package the human chose (see Decisions). Without a
271
301
  custom domain bound to its proxy, pass `--public-access=zerops-subdomain`; the default is
272
302
  `custom-domain`, which serves no host until you bind one.
@@ -340,8 +370,18 @@ install the newest patch instead (step 6 upgrades an installation).
340
370
  `deploy interrupted: …; run the deploy again` lost Control mid-run, typically to step 3's workflow
341
371
  redeploying it: deploy again once Control is back.
342
372
 
343
- The deploy fails when the repository at the deployed commit does not match the registered manifest.
344
- Commit and push, rebuild the manifest, `apps environments put` it, and deploy again.
373
+ `source resolve failed (descriptor_mismatch): zerops.yaml at commit <sha> has sha256 <a>, expected sha256
374
+ <b>` means the `zerops.yaml` at the deployed commit is not the one the environment's manifest was built
375
+ from. Deploying again fails the same way. Either side can be the newer one:
376
+ - The manifest is newer: it was built from a `zerops.yaml` that is not pushed yet. Commit and push it (or
377
+ deploy the ref that has it), and deploy again. Do not rebuild the manifest from the older commit: that
378
+ drops the change, and the next deploy succeeds without it.
379
+ - The commit is newer: `zerops.yaml` changed (its `build.base`, say) after the manifest was built. From a
380
+ checkout of that commit, rebuild the manifest (`fabrika app build --env=<name>`, plus `--config` if the
381
+ app uses another config), send it with `control apps environments put`, and deploy again.
382
+
383
+ The log line prints the `put` command with the environment's stored domain and trigger ref: `put` clears
384
+ either one when the flag is left out.
345
385
 
346
386
  On an environment named `prod`, a change that widens access waits for a person to approve it in the
347
387
  console before it deploys.
@@ -427,6 +467,44 @@ Without a transport, a contract whose job declares `mailer: 'installation'` stil
427
467
  its jobs see that mail is not available and leave their messages queued, and after step 5 the next run sends them. On
428
468
  0.7 or newer the relay accepts and holds the messages, and Control sends them once it has a transport.
429
469
 
470
+ ## Turn on single sign-on
471
+
472
+ An installation signs people in with a password unless it was installed with `--auth-methods`. To add sign-in through
473
+ an OpenID Connect identity provider to an existing installation:
474
+
475
+ No `fabrika` command does this, and none undoes it: `platform deploy` and `platform upgrade` write none of the variables
476
+ below and remove none, so what you set survives every later deploy and upgrade. `install` cannot be re-run.
477
+
478
+ 1. At the identity provider, create a web application client and register its redirect URI as
479
+ `https://<IAM host>/auth/callback`, with the IAM host from step 1. Note the issuer URL (IAM reads
480
+ `<issuer>/.well-known/openid-configuration`), the client id and the client secret.
481
+ 2. Set these variables on the `iam` service, in the Zerops GUI or with `zcli`. The `OIDC_*` names carry no `FABRIKA_IAM_`
482
+ prefix: they are the names IAM reads.
483
+
484
+ | Variable | Value |
485
+ | ------------------------------ | ----------------------------------------------------------------------- |
486
+ | `FABRIKA_IAM_OIDC_ENABLED` | `true` |
487
+ | `FABRIKA_IAM_PASSWORD_ENABLED` | `true` keeps password sign-in beside single sign-on, `false` removes it |
488
+ | `OIDC_ISSUER` | the issuer URL |
489
+ | `OIDC_CLIENT_ID` | the client id |
490
+ | `OIDC_CLIENT_SECRET` | the client secret, stored SENSITIVE |
491
+
492
+ A readable `OIDC_CLIENT_SECRET` is read by every member of the project, and `platform deploy` refuses to run while it
493
+ is readable. A variable already stored readable does not become sensitive through `zops env set --sensitive`: delete
494
+ it and add it again as a secret one in the GUI.
495
+ 3. Restart `iam`. It reads these at boot, and with `FABRIKA_IAM_OIDC_ENABLED=true` it refuses to start while any of the
496
+ three `OIDC_*` is missing, which takes sign-in down: read its log until it serves again. The sign-in page then
497
+ offers single sign-on beside the password form, or, with password off, goes straight to the provider.
498
+ 4. Single sign-on admits only someone IAM already knows: an invited address or an existing user, matched by the e-mail
499
+ the provider verified. Anyone else is refused (`not_admitted`). The first sign-in links the person to the provider's
500
+ subject. With password off, `platform admin` admits the address and grants it the admin role without an enrollment;
501
+ that person signs in with single sign-on. The Zerops installer offers no domain-wide admission (Cloudflare's
502
+ `--human-email-domains`): to admit everyone of a domain without an invitation, set `HUMAN_EMAIL_DOMAINS` on `iam` to
503
+ a JSON array such as `["example.com"]` (unprefixed, like the `OIDC_*` names) and restart it.
504
+
505
+ To turn single sign-on off again, set `FABRIKA_IAM_OIDC_ENABLED=false` with `FABRIKA_IAM_PASSWORD_ENABLED=true` and
506
+ restart `iam`; it refuses to start with both off.
507
+
430
508
  ## When something fails
431
509
 
432
510
  - Every refusal names its flag or variable. Fix that one value and re-run. `init`, `admin`, `deploy` and