@fabrika/provider-contract 0.9.0-dev.2 → 0.9.0-dev.21
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 +14 -3
- package/src/app-cli.ts +81 -0
- package/src/conformance.ts +221 -0
- package/src/control.ts +218 -22
- package/src/index.ts +1 -0
- package/src/plain-credentials.ts +278 -0
- package/types/src/app-cli.d.ts +46 -0
- package/types/src/conformance.d.ts +22 -0
- package/types/src/control.d.ts +210 -22
- package/types/src/index.d.ts +1 -0
- package/types/src/plain-credentials.d.ts +16 -0
package/src/control.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import type { AppSchema, ContractArtifact } from '@fabrika/auth-core'
|
|
1
|
+
import type { ApplicationObjects, AppSchema, ContractArtifact, ManagedEnvironment } from '@fabrika/auth-core'
|
|
2
|
+
import type { InstallationBrand } from '@fabrika/proxy-core/brand'
|
|
2
3
|
import type { JsonValue, ProviderEnvelope } from './json'
|
|
3
4
|
|
|
4
5
|
/** Events whose persistence and presentation belong to the control plane. */
|
|
@@ -15,8 +16,11 @@ export interface ProviderRunEvents {
|
|
|
15
16
|
boundary(): Promise<void>
|
|
16
17
|
}
|
|
17
18
|
|
|
18
|
-
/**
|
|
19
|
-
|
|
19
|
+
/**
|
|
20
|
+
* Complete platform-owned runtime state, parsed by Control (`parseManagedEnvironment`). A provider writes each entry as
|
|
21
|
+
* a secret when it is a `credential`, removes one whose value is null, and removes the stale ones `staleManagedVariables` names.
|
|
22
|
+
*/
|
|
23
|
+
export type ProviderManagedEnvironment = ManagedEnvironment
|
|
20
24
|
|
|
21
25
|
/** Provider-neutral coordinates for obtaining one app revision. */
|
|
22
26
|
export interface ProviderSource {
|
|
@@ -41,8 +45,7 @@ export interface ProviderDeploymentNamespace {
|
|
|
41
45
|
readonly target: ProviderEnvelope
|
|
42
46
|
}
|
|
43
47
|
|
|
44
|
-
|
|
45
|
-
export const FRAMEWORK_RELEASE_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/
|
|
48
|
+
export { FRAMEWORK_RELEASE_PATTERN } from '@fabrika/auth-core'
|
|
46
49
|
|
|
47
50
|
/**
|
|
48
51
|
* The access Control approved for one application environment (ADR-0050): the contract the proxy enforces and the
|
|
@@ -64,6 +67,12 @@ export interface ProviderApprovedAccess {
|
|
|
64
67
|
* the framework minor it pins (ADR-0062). Its build checks with that release.
|
|
65
68
|
*/
|
|
66
69
|
readonly checker: string
|
|
70
|
+
/**
|
|
71
|
+
* The `@fabrika/app` release the application's `bun.lock` pins (`FRAMEWORK_RELEASE_PATTERN`), which a release gate
|
|
72
|
+
* reads: `checker` is this platform's patch of that minor, newer than a prerelease pin. Absent in an access Control
|
|
73
|
+
* approved before it recorded the pin.
|
|
74
|
+
*/
|
|
75
|
+
readonly framework?: string
|
|
67
76
|
}
|
|
68
77
|
|
|
69
78
|
/**
|
|
@@ -87,12 +96,18 @@ export interface ProviderEnvironment {
|
|
|
87
96
|
* application's proxy manifest entry as `crossOrigins`.
|
|
88
97
|
*/
|
|
89
98
|
readonly crossOrigins?: readonly string[]
|
|
99
|
+
/**
|
|
100
|
+
* The origin of the environment's active Operations ingest DSN, never the DSN: a contract application's proxy admits
|
|
101
|
+
* it in `connect-src`. Control sets it on a deploy; absent while the environment has no active ingest.
|
|
102
|
+
*/
|
|
103
|
+
readonly operationsOrigin?: string
|
|
90
104
|
readonly namespace?: ProviderDeploymentNamespace
|
|
91
105
|
readonly target: ProviderEnvelope
|
|
92
106
|
readonly artifact: ProviderEnvelope
|
|
93
107
|
/**
|
|
94
108
|
* The environment's approved contract, from Control's `approvedSnapshot`. Absent when nothing is approved: then a
|
|
95
109
|
* provider publishes no endpoint table and reconciles no IAM schema, whatever the artifact claims (ADR-0050).
|
|
110
|
+
* Control refuses a non-dry deploy without it.
|
|
96
111
|
*/
|
|
97
112
|
readonly access?: ProviderApprovedAccess
|
|
98
113
|
}
|
|
@@ -117,6 +132,13 @@ export interface ProviderSourceResolutionInput {
|
|
|
117
132
|
readonly signal: AbortSignal
|
|
118
133
|
}
|
|
119
134
|
|
|
135
|
+
/** The build descriptor of a deploy's commit: its repository path and its text. */
|
|
136
|
+
export interface ProviderSourceDescriptorInput {
|
|
137
|
+
readonly environment: ProviderEnvironment
|
|
138
|
+
readonly path: string
|
|
139
|
+
readonly contents: string
|
|
140
|
+
}
|
|
141
|
+
|
|
120
142
|
/** The exact source revision a provider resolved before starting deploy work. */
|
|
121
143
|
export interface ProviderSourceResolution {
|
|
122
144
|
readonly commitSha: string
|
|
@@ -146,13 +168,31 @@ export interface ProviderDeployInput {
|
|
|
146
168
|
/** Platform-owned runtime configuration, separate from operator-managed application vars. */
|
|
147
169
|
readonly managedEnvironment: ProviderManagedEnvironment
|
|
148
170
|
/**
|
|
149
|
-
*
|
|
150
|
-
*
|
|
151
|
-
* Absent when the app has no public origin at all, which leaves IAM's registry untouched.
|
|
171
|
+
* The object that serves the environment's ordinary traffic and the objects its ops channel reaches, as Control records
|
|
172
|
+
* them (ADR-0070 §9). A provider whose application runs in no object ignores it; absent, the provider's defaults.
|
|
152
173
|
*/
|
|
153
|
-
readonly
|
|
174
|
+
readonly applicationObjects?: ApplicationObjects
|
|
175
|
+
/**
|
|
176
|
+
* Present when the deploy brings migration files with a `dataLoss` statement of any kind, which may change stored data, and that the version running does not hold
|
|
177
|
+
* (ADR-0050): the provider backs up the application's database, and waits until the backup is stored, before any
|
|
178
|
+
* version that can run them starts. A backup that fails or does not finish fails the run with nothing deployed.
|
|
179
|
+
* Control hands it only to a provider without `dataOperations`, whose migration phase backs up itself (ADR-0070 §8),
|
|
180
|
+
* and never to a dry run or a dev bootstrap.
|
|
181
|
+
*/
|
|
182
|
+
readonly backupBeforeMigrations?: { readonly migrations: readonly string[] }
|
|
154
183
|
readonly dryRun: boolean
|
|
155
184
|
readonly sourceBinding?: ProviderSourceBinding
|
|
185
|
+
/**
|
|
186
|
+
* Present on a dev bootstrap: the provider deploys into this workspace's sandbox, which `devSandboxes.ensure` created
|
|
187
|
+
* before the run, and serves it at `origin`. Absent on every other deploy.
|
|
188
|
+
*/
|
|
189
|
+
readonly devSandbox?: {
|
|
190
|
+
readonly workspaceId: string
|
|
191
|
+
readonly sandboxId: string
|
|
192
|
+
readonly origin: string
|
|
193
|
+
/** See `ProviderDevSandboxInput.sandboxKey`. */
|
|
194
|
+
readonly sandboxKey: string
|
|
195
|
+
}
|
|
156
196
|
/** Optional short-lived, run-scoped Operations artifact destination. */
|
|
157
197
|
readonly artifactUpload?: {
|
|
158
198
|
readonly url: string
|
|
@@ -167,7 +207,10 @@ export interface ProviderDeployInput {
|
|
|
167
207
|
readonly events: ProviderRunEvents
|
|
168
208
|
}
|
|
169
209
|
|
|
170
|
-
/**
|
|
210
|
+
/**
|
|
211
|
+
* A terminal provider operation result. `succeeded` means the version is live: Control then writes the environment's
|
|
212
|
+
* approved IAM schema itself (ADR-0011), so a provider never calls IAM for an application.
|
|
213
|
+
*/
|
|
171
214
|
export interface ProviderTerminalOutcome {
|
|
172
215
|
readonly state: 'succeeded' | 'failed'
|
|
173
216
|
readonly exitCode?: number
|
|
@@ -230,14 +273,10 @@ export interface ProviderRunReference {
|
|
|
230
273
|
|
|
231
274
|
export interface ProviderCancelInput extends ProviderRunReference {
|
|
232
275
|
readonly signal: AbortSignal
|
|
233
|
-
/** See `ProviderDeployInput.returnOrigins`; a cancel that settles an activated deploy projects the same set. */
|
|
234
|
-
readonly returnOrigins?: readonly string[]
|
|
235
276
|
}
|
|
236
277
|
|
|
237
278
|
export interface ProviderReconcileInput extends ProviderRunReference {
|
|
238
279
|
readonly signal: AbortSignal
|
|
239
|
-
/** See `ProviderDeployInput.returnOrigins`; a provider that settles a deploy here projects the same set. */
|
|
240
|
-
readonly returnOrigins?: readonly string[]
|
|
241
280
|
/** Append a line to the run's log. */
|
|
242
281
|
log?(line: string): Promise<void>
|
|
243
282
|
}
|
|
@@ -331,6 +370,34 @@ export interface ProviderNamespaceMember {
|
|
|
331
370
|
readonly operationsOrigin?: string
|
|
332
371
|
/** See `ProviderEnvironment.access`: the proxy table of a contract application comes only from here. */
|
|
333
372
|
readonly access?: ProviderApprovedAccess
|
|
373
|
+
/**
|
|
374
|
+
* Present for a dev member, which is routed ONLY through these entries (none while it has no sandbox), never through
|
|
375
|
+
* its own `domain` and `access`.
|
|
376
|
+
*/
|
|
377
|
+
readonly devSandboxes?: readonly ProviderNamespaceDevSandbox[]
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
/** One workspace sandbox of a `dev` member, which the namespace proxy routes as its own entry. */
|
|
381
|
+
export interface ProviderNamespaceDevSandbox {
|
|
382
|
+
readonly workspaceId: string
|
|
383
|
+
/** The public host the proxy answers the workspace on (`<workspaceId>.<domain>`). */
|
|
384
|
+
readonly host: string
|
|
385
|
+
/** See `ProviderDevSandbox.upstreamHost`. */
|
|
386
|
+
readonly upstreamHost: string
|
|
387
|
+
/** See `ProviderNamespaceMember.proxySecret`: sealed per workspace. */
|
|
388
|
+
readonly proxySecret?: string
|
|
389
|
+
/** The access of the workspace's own published bootstrap run. */
|
|
390
|
+
readonly access: ProviderApprovedAccess
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
/** What decides the hosts a namespace entry point routes one member on: `ProviderNamespaceMember` without its secrets. */
|
|
394
|
+
export interface ProviderNamespaceMemberRouting {
|
|
395
|
+
readonly appId: string
|
|
396
|
+
readonly env: string
|
|
397
|
+
readonly domain?: string
|
|
398
|
+
readonly artifact: ProviderEnvelope
|
|
399
|
+
readonly access?: ProviderApprovedAccess
|
|
400
|
+
readonly devSandboxes?: readonly Pick<ProviderNamespaceDevSandbox, 'workspaceId' | 'host'>[]
|
|
334
401
|
}
|
|
335
402
|
|
|
336
403
|
/** One idempotent namespace lifecycle invocation. */
|
|
@@ -338,6 +405,16 @@ export interface ProviderNamespaceMutationInput {
|
|
|
338
405
|
readonly namespace: ProviderDeploymentNamespace
|
|
339
406
|
/** Every app environment assigned to the namespace, read under its lease. */
|
|
340
407
|
readonly members: readonly ProviderNamespaceMember[]
|
|
408
|
+
/**
|
|
409
|
+
* The installation's client logo for the pages the namespace's proxy answers with (ADR-0066), read from IAM for this
|
|
410
|
+
* mutation; absent or null shows the fabrika mark. A provider passes it only to a proxy that can parse it.
|
|
411
|
+
*/
|
|
412
|
+
readonly brand?: InstallationBrand | null
|
|
413
|
+
/**
|
|
414
|
+
* Present when a member is a `dev` environment: the namespace's sandbox host is provisioned with it as its API key, and
|
|
415
|
+
* see `ProviderDevSandboxInput.sandboxKey`. Absent, the provider provisions no sandbox host.
|
|
416
|
+
*/
|
|
417
|
+
readonly sandboxKey?: string
|
|
341
418
|
readonly signal: AbortSignal
|
|
342
419
|
readonly events: ProviderNamespaceEvents
|
|
343
420
|
}
|
|
@@ -366,6 +443,18 @@ export const PROVIDER_NAMESPACE_IMMUTABLE = 'namespaceImmutable'
|
|
|
366
443
|
*/
|
|
367
444
|
export const PROVIDER_NAMESPACE_UPDATE_UNCONFIRMED = 'namespaceUpdateUnconfirmed'
|
|
368
445
|
|
|
446
|
+
/**
|
|
447
|
+
* The `code` of a `ProviderNamespaceError` a `devSandboxes` call throws when the namespace's sandbox host has no room
|
|
448
|
+
* to create or wake one more sandbox. Nothing changed; it succeeds once another sandbox is parked or removed.
|
|
449
|
+
*/
|
|
450
|
+
export const PROVIDER_DEV_CAPACITY = 'devCapacity'
|
|
451
|
+
|
|
452
|
+
/**
|
|
453
|
+
* The `code` of a `ProviderNamespaceError` a `devSandboxes` call throws when the namespace has no sandbox host yet.
|
|
454
|
+
* Nothing changed; it succeeds once a namespace mutation handed the sandbox host key has created the host.
|
|
455
|
+
*/
|
|
456
|
+
export const PROVIDER_DEV_HOST_PENDING = 'devHostPending'
|
|
457
|
+
|
|
369
458
|
/** One provider-described change, safe to audit: names and values only, never a credential. */
|
|
370
459
|
export interface ProviderNamespaceChange {
|
|
371
460
|
readonly field: string
|
|
@@ -470,6 +559,19 @@ export interface ProviderNamespaceOperator {
|
|
|
470
559
|
present(namespace: ProviderDeploymentNamespace): ProviderNamespacePresentation
|
|
471
560
|
}
|
|
472
561
|
|
|
562
|
+
/** The app-owned claims of one namespace whose resources Control is asked to confirm gone. */
|
|
563
|
+
export interface ProviderClaimedResourcesInput {
|
|
564
|
+
readonly namespace: ProviderDeploymentNamespace
|
|
565
|
+
readonly resourceKeys: readonly string[]
|
|
566
|
+
readonly signal: AbortSignal
|
|
567
|
+
}
|
|
568
|
+
|
|
569
|
+
/** What the provider observed for one claimed resource. */
|
|
570
|
+
export interface ProviderClaimedResource {
|
|
571
|
+
readonly resourceKey: string
|
|
572
|
+
readonly exists: boolean
|
|
573
|
+
}
|
|
574
|
+
|
|
473
575
|
/** Optional placement lifecycle owned by providers that use deployment namespaces. */
|
|
474
576
|
export interface ProviderNamespaceCapabilities {
|
|
475
577
|
normalize(namespace: ProviderDeploymentNamespace): ProviderDeploymentNamespace
|
|
@@ -486,24 +588,85 @@ export interface ProviderNamespaceCapabilities {
|
|
|
486
588
|
reconcile(input: ProviderNamespaceMutationInput): Promise<ProviderDeploymentNamespace>
|
|
487
589
|
/** Absent means the namespace has no entry point that follows its members. */
|
|
488
590
|
republish?(input: ProviderNamespaceRepublishInput): Promise<ProviderNamespaceRepublishResult>
|
|
591
|
+
/**
|
|
592
|
+
* The hosts the namespace's entry point routes this member on, lower-cased, by the rule its compiler applies; none for
|
|
593
|
+
* a member it does not route. Throws for a member it cannot route. Absent means no member is routed by host.
|
|
594
|
+
*/
|
|
595
|
+
memberHosts?(member: ProviderNamespaceMemberRouting): readonly string[]
|
|
596
|
+
/**
|
|
597
|
+
* Read-only: whether each claimed resource still exists, one answer per key. Throws when it cannot tell, so Control
|
|
598
|
+
* releases a claim only over a resource the provider confirmed gone. Absent means no claim can be released.
|
|
599
|
+
*/
|
|
600
|
+
claimedResources?(input: ProviderClaimedResourcesInput): Promise<readonly ProviderClaimedResource[]>
|
|
489
601
|
/** Absent means the provider changes no namespace in place. */
|
|
490
602
|
readonly updates?: ProviderNamespaceUpdates
|
|
491
603
|
readonly operator?: ProviderNamespaceOperator
|
|
492
604
|
}
|
|
493
605
|
|
|
494
|
-
|
|
495
|
-
|
|
606
|
+
export interface ProviderAuthoring {
|
|
607
|
+
/** The file NAMES (no `/`) that configure the provider's deploy; a workspace changes none of them, at any depth. */
|
|
608
|
+
readonly protectedFiles: readonly string[]
|
|
609
|
+
}
|
|
610
|
+
|
|
611
|
+
/** The provider's handle on one workspace sandbox, which Control persists; stable for the workspace's life. */
|
|
612
|
+
export interface ProviderDevSandboxRef {
|
|
613
|
+
readonly sandboxId: string
|
|
614
|
+
}
|
|
615
|
+
|
|
616
|
+
/** One running workspace sandbox of a `dev` environment. */
|
|
617
|
+
export interface ProviderDevSandbox {
|
|
618
|
+
readonly sandboxId: string
|
|
619
|
+
/** The base image the sandbox was created from. */
|
|
620
|
+
readonly baseDigest: string
|
|
621
|
+
/** The Host the namespace proxy sends to reach the sandbox's application port (e.g. `3000-<id>.<box domain>`). */
|
|
622
|
+
readonly upstreamHost: string
|
|
623
|
+
}
|
|
624
|
+
|
|
625
|
+
/** Create a workspace's sandbox, or return the one it already has. */
|
|
626
|
+
export interface ProviderDevSandboxEnsureInput {
|
|
627
|
+
readonly environment: ProviderEnvironment
|
|
628
|
+
readonly workspaceId: string
|
|
629
|
+
/** See `ProviderDevSandboxInput.sandboxKey`. */
|
|
630
|
+
readonly sandboxKey: string
|
|
631
|
+
readonly signal: AbortSignal
|
|
632
|
+
}
|
|
633
|
+
|
|
634
|
+
/** One lifecycle call on an existing workspace sandbox. */
|
|
635
|
+
export interface ProviderDevSandboxInput {
|
|
636
|
+
readonly environment: ProviderEnvironment
|
|
637
|
+
readonly sandbox: ProviderDevSandboxRef
|
|
638
|
+
/** The bearer of the namespace's sandbox host API, composed by Control from its vault for this call; never persisted or logged. */
|
|
639
|
+
readonly sandboxKey: string
|
|
640
|
+
readonly signal: AbortSignal
|
|
641
|
+
}
|
|
642
|
+
|
|
643
|
+
/** Remove a workspace's sandbox; with no recorded `sandbox`, the one an unrecorded `ensure` may have created. */
|
|
644
|
+
export interface ProviderDevSandboxRemoveInput {
|
|
496
645
|
readonly environment: ProviderEnvironment
|
|
646
|
+
readonly workspaceId: string
|
|
647
|
+
readonly sandbox: ProviderDevSandboxRef | null
|
|
648
|
+
/** See `ProviderDevSandboxInput.sandboxKey`. */
|
|
649
|
+
readonly sandboxKey: string
|
|
497
650
|
readonly signal: AbortSignal
|
|
498
651
|
}
|
|
499
652
|
|
|
500
653
|
/**
|
|
501
|
-
* The
|
|
502
|
-
*
|
|
654
|
+
* The per-workspace sandboxes of a `dev` environment outside a run. Every call is idempotent: `ensure` creates at most
|
|
655
|
+
* one sandbox per `workspaceId` and returns it running, `park` and `wake` converge on their state, and `remove` treats a
|
|
656
|
+
* sandbox already gone as removed. A full sandbox host throws `PROVIDER_DEV_CAPACITY`, a namespace without one yet
|
|
657
|
+
* `PROVIDER_DEV_HOST_PENDING`; `remove` there is a no-op, since no sandbox can exist.
|
|
503
658
|
*/
|
|
504
|
-
export interface
|
|
505
|
-
|
|
506
|
-
|
|
659
|
+
export interface ProviderDevSandboxes {
|
|
660
|
+
/**
|
|
661
|
+
* Mutation-free check that the environment's placement can serve a workspace sandbox. Control calls it before it
|
|
662
|
+
* records one, because a recorded sandbox reaches every later republish of the namespace. A refusal is a
|
|
663
|
+
* `ProviderNamespaceError` that is not retryable, whose one-line message the author may read; any other throw is a failure.
|
|
664
|
+
*/
|
|
665
|
+
admit(input: { readonly environment: ProviderEnvironment }): void
|
|
666
|
+
ensure(input: ProviderDevSandboxEnsureInput): Promise<ProviderDevSandbox>
|
|
667
|
+
park(input: ProviderDevSandboxInput): Promise<void>
|
|
668
|
+
wake(input: ProviderDevSandboxInput): Promise<void>
|
|
669
|
+
remove(input: ProviderDevSandboxRemoveInput): Promise<void>
|
|
507
670
|
}
|
|
508
671
|
|
|
509
672
|
/**
|
|
@@ -517,6 +680,13 @@ export interface ControlProvider {
|
|
|
517
680
|
/** Absent means core stores the registration as submitted. */
|
|
518
681
|
normalizeRegistration?(input: ProviderRegistrationInput): ProviderRegistration
|
|
519
682
|
resolveSource?(input: ProviderSourceResolutionInput): Promise<ProviderSourceResolution>
|
|
683
|
+
/**
|
|
684
|
+
* The environment's artifact with the build descriptor a deploy's commit carries, validated as a registration is; it
|
|
685
|
+
* throws a refusal that names the refused key. Control calls it from a deploy run whose commit holds a descriptor the
|
|
686
|
+
* registered artifact does not, deploys with the result, and stores it once the run's publication passed (ADR-0043).
|
|
687
|
+
* Null when the provider does not re-register this artifact from a commit; absent means it re-registers none.
|
|
688
|
+
*/
|
|
689
|
+
withSourceDescriptor?(input: ProviderSourceDescriptorInput): Promise<ProviderEnvelope | null>
|
|
520
690
|
/**
|
|
521
691
|
* Mutation-free check of a candidate's compatibility with its placement. Control calls it before publishing the
|
|
522
692
|
* snapshot, under the namespace lease, on every publication attempt. The candidate is not yet approved access.
|
|
@@ -527,8 +697,29 @@ export interface ControlProvider {
|
|
|
527
697
|
reconcile?(input: ProviderReconcileInput): Promise<ProviderReconcileOutcome>
|
|
528
698
|
readonly secrets?: ProviderManagedSecrets
|
|
529
699
|
readonly namespaces?: ProviderNamespaceCapabilities
|
|
700
|
+
/** MCP authoring (ADR-0049): an environment of this provider can be an authoring target. Absent means none can. */
|
|
701
|
+
readonly authoring?: ProviderAuthoring
|
|
702
|
+
/**
|
|
703
|
+
* Every application environment gets `FABRIKA_PROXY_SECRET`, with or without a namespace proxy: the provider's own
|
|
704
|
+
* hop to the application carries it (Cloudflare's Worker to its Durable Object, ADR-0065). Absent means only a
|
|
705
|
+
* namespace proxy's environments get one.
|
|
706
|
+
*/
|
|
707
|
+
readonly applicationHopSecret?: true
|
|
530
708
|
/** Absent means the provider runs no `dev` environment, and Control refuses one. */
|
|
531
|
-
readonly
|
|
709
|
+
readonly devSandboxes?: ProviderDevSandboxes
|
|
710
|
+
/**
|
|
711
|
+
* Whether an environment at this approved access is served the ops channel through which Control reaches its object
|
|
712
|
+
* (ADR-0069), so its deploy gets `FABRIKA_OPS_KEY_DIGESTS`. The release gate is the provider's, so core keeps no
|
|
713
|
+
* release logic. Absent means no environment of this provider is.
|
|
714
|
+
*/
|
|
715
|
+
opsChannel?(access: ProviderApprovedAccess): boolean
|
|
716
|
+
/**
|
|
717
|
+
* Whether the object at this approved access, served the ops channel, also holds the maintenance barrier (`state`,
|
|
718
|
+
* `migrate`) and serves Control's data operations: the daily backups, a deploy's migration phase and the side restore
|
|
719
|
+
* (ADR-0069 §3, ADR-0070). A release can serve the channel without them. Absent means no environment of this
|
|
720
|
+
* provider is.
|
|
721
|
+
*/
|
|
722
|
+
dataOperations?(access: ProviderApprovedAccess): boolean
|
|
532
723
|
/** Absent means the provider deploys public sources only. */
|
|
533
724
|
readonly source?: ProviderSourceCapabilities
|
|
534
725
|
/**
|
|
@@ -547,4 +738,9 @@ export interface ControlProvider {
|
|
|
547
738
|
* access snapshot there (ADR-0050). Absent means the repository root.
|
|
548
739
|
*/
|
|
549
740
|
applicationRoot?(source: ProviderSource): string | null
|
|
741
|
+
/**
|
|
742
|
+
* The database an application of this provider runs its migrations on, which Control classifies them for: SQLite in
|
|
743
|
+
* the application's Durable Object on Cloudflare (ADR-0065). Absent means Postgres.
|
|
744
|
+
*/
|
|
745
|
+
readonly applicationDialect?: 'postgres' | 'sqlite'
|
|
550
746
|
}
|
package/src/index.ts
CHANGED
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
// Whether a value about to sit somewhere readable looks like a credential.
|
|
2
|
+
//
|
|
3
|
+
// A plain variable is read by everyone who may read the configuration it lives in: on Zerops every member of the
|
|
4
|
+
// project, on Control everyone who manages the application. A credential belongs where nobody reads it back (a
|
|
5
|
+
// sensitive service variable, an application secret). The check is a heuristic over the NAME and the VALUE, and it
|
|
6
|
+
// errs towards refusing, so each place that runs it has an explicit opt-out for a value it got wrong.
|
|
7
|
+
//
|
|
8
|
+
// Nothing here returns, logs or embeds the value: a finding names only why it matched.
|
|
9
|
+
|
|
10
|
+
/** Why a name and value look like a credential. `because` completes "… looks like a credential: <because>". */
|
|
11
|
+
export interface PlainCredentialFinding {
|
|
12
|
+
readonly basis: 'name' | 'value'
|
|
13
|
+
readonly because: string
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/** Words in a variable name that mark a credential on their own; `BASIC` followed by `AUTH` does too. */
|
|
17
|
+
const CREDENTIAL_WORDS: ReadonlySet<string> = new Set([
|
|
18
|
+
'TOKEN',
|
|
19
|
+
'SECRET',
|
|
20
|
+
'PASSWORD',
|
|
21
|
+
'PASSWD',
|
|
22
|
+
'PASS',
|
|
23
|
+
'PASSPHRASE',
|
|
24
|
+
'PWD',
|
|
25
|
+
'CREDENTIAL',
|
|
26
|
+
'CREDENTIALS',
|
|
27
|
+
'APIKEY',
|
|
28
|
+
'PRIVATEKEY',
|
|
29
|
+
'BASICAUTH',
|
|
30
|
+
'HTPASSWD',
|
|
31
|
+
])
|
|
32
|
+
|
|
33
|
+
/** Words that make `KEY` (or `KEYS`) something other than a credential: `KEY_ID`, `PUBLIC_KEY`, `SITE_KEY`, `CACHE_KEY`. */
|
|
34
|
+
// Not `PRIMARY`: some providers call a secret a primary key (an account's primary access key).
|
|
35
|
+
const NON_CREDENTIAL_KEY_WORDS: ReadonlySet<string> = new Set([
|
|
36
|
+
'ID',
|
|
37
|
+
'IDS',
|
|
38
|
+
'PUBLIC',
|
|
39
|
+
'PUBLISHABLE',
|
|
40
|
+
'SITE',
|
|
41
|
+
'CACHE',
|
|
42
|
+
'PARTITION',
|
|
43
|
+
'SORT',
|
|
44
|
+
'FOREIGN',
|
|
45
|
+
])
|
|
46
|
+
|
|
47
|
+
/** The words beside `KEY` that make its value public, not merely not a credential. */
|
|
48
|
+
const PUBLIC_KEY_WORDS: ReadonlySet<string> = new Set(['PUBLIC', 'PUBLISHABLE', 'SITE'])
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* A last word that makes the name describe a credential rather than hold one: `TOKEN_URL`, `PASSWORD_MIN_LENGTH`,
|
|
52
|
+
* `SECRET_NAME`, `API_KEY_HEADER`.
|
|
53
|
+
*/
|
|
54
|
+
const DESCRIPTOR_WORDS: ReadonlySet<string> = new Set([
|
|
55
|
+
'URL',
|
|
56
|
+
'URI',
|
|
57
|
+
'ENDPOINT',
|
|
58
|
+
'HOST',
|
|
59
|
+
'ORIGIN',
|
|
60
|
+
'PATH',
|
|
61
|
+
'FILE',
|
|
62
|
+
'DIR',
|
|
63
|
+
'ID',
|
|
64
|
+
'IDS',
|
|
65
|
+
'NAME',
|
|
66
|
+
'NAMES',
|
|
67
|
+
'HEADER',
|
|
68
|
+
'PARAM',
|
|
69
|
+
'TTL',
|
|
70
|
+
'LIFETIME',
|
|
71
|
+
'EXPIRY',
|
|
72
|
+
'EXPIRES',
|
|
73
|
+
'LENGTH',
|
|
74
|
+
'SIZE',
|
|
75
|
+
'ALGORITHM',
|
|
76
|
+
'ISSUER',
|
|
77
|
+
'AUDIENCE',
|
|
78
|
+
'MODE',
|
|
79
|
+
'ENABLED',
|
|
80
|
+
'REQUIRED',
|
|
81
|
+
'PREFIX',
|
|
82
|
+
'POLICY',
|
|
83
|
+
'TYPE',
|
|
84
|
+
'VERSION',
|
|
85
|
+
'COUNT',
|
|
86
|
+
'LIMIT',
|
|
87
|
+
'TIMEOUT',
|
|
88
|
+
'REALM',
|
|
89
|
+
])
|
|
90
|
+
|
|
91
|
+
/** `FABRIKA_EMAIL_POSTMARK_SERVER_TOKEN`, `apiKey`, `basic-auth.password` → upper-case words. */
|
|
92
|
+
const nameWords = (name: string): readonly string[] =>
|
|
93
|
+
name
|
|
94
|
+
.replace(/([a-z0-9])([A-Z])/g, '$1_$2')
|
|
95
|
+
.toUpperCase()
|
|
96
|
+
.split(/[^A-Z0-9]+/)
|
|
97
|
+
.filter((word) => word !== '')
|
|
98
|
+
|
|
99
|
+
/** Whether the `KEY` at `index` is an id, a public key or a cache key: a word beside it says so. */
|
|
100
|
+
const nonCredentialKey = (words: readonly string[], index: number): boolean => {
|
|
101
|
+
const before = words[index - 1]
|
|
102
|
+
const after = words[index + 1]
|
|
103
|
+
return (before !== undefined && NON_CREDENTIAL_KEY_WORDS.has(before)) || (after !== undefined && NON_CREDENTIAL_KEY_WORDS.has(after))
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/** The word of a credential name that matched, or null. */
|
|
107
|
+
const credentialWordIn = (words: readonly string[]): string | null => {
|
|
108
|
+
const last = words.at(-1)
|
|
109
|
+
if (last === undefined || DESCRIPTOR_WORDS.has(last)) return null
|
|
110
|
+
for (const [index, word] of words.entries()) {
|
|
111
|
+
if (CREDENTIAL_WORDS.has(word)) return word
|
|
112
|
+
if (word === 'BASIC' && words[index + 1] === 'AUTH') return 'BASIC_AUTH'
|
|
113
|
+
if ((word === 'KEY' || word === 'KEYS') && !nonCredentialKey(words, index)) return word
|
|
114
|
+
}
|
|
115
|
+
return null
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* Whether the name says its value is public: a publishable, site or public key, or an id, in a name with no credential
|
|
120
|
+
* word. Such a value is often long and random (`pk_live_…`, a reCAPTCHA site key, a VAPID public key), so the
|
|
121
|
+
* random-string rule does not apply to it. A name that also says `SECRET` (`SECRET_KEY_ID`) is not public.
|
|
122
|
+
*/
|
|
123
|
+
const namesAPublicValue = (words: readonly string[]): boolean => {
|
|
124
|
+
if (words.some((word, index) => CREDENTIAL_WORDS.has(word) || (word === 'BASIC' && words[index + 1] === 'AUTH'))) return false
|
|
125
|
+
const publicKey = words.some((word, index) =>
|
|
126
|
+
(word === 'KEY' || word === 'KEYS')
|
|
127
|
+
&& [words[index - 1], words[index + 1]].some((beside) => beside !== undefined && PUBLIC_KEY_WORDS.has(beside))
|
|
128
|
+
)
|
|
129
|
+
return publicKey || words.at(-1) === 'ID' || words.at(-1) === 'IDS'
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/**
|
|
133
|
+
* A Zerops or shell reference (`${db_password}`) names a value held elsewhere, so it is not one here. Removing them
|
|
134
|
+
* leaves the literal part of a value; a value that is only references holds no literal at all.
|
|
135
|
+
*/
|
|
136
|
+
const withoutReferences = (value: string): string => value.replace(/\$\{[^}]*\}/g, '')
|
|
137
|
+
|
|
138
|
+
/** Prefixes that issuers put on their tokens. */
|
|
139
|
+
const TOKEN_PREFIXES: readonly (readonly [RegExp, string])[] = [
|
|
140
|
+
[/^px_[A-Za-z0-9_-]{8,}/, 'a Fabrika key'],
|
|
141
|
+
[/^(ghp|gho|ghs|ghu|ghr)_[A-Za-z0-9]{20,}/, 'a GitHub token'],
|
|
142
|
+
[/^github_pat_[A-Za-z0-9_]{20,}/, 'a GitHub token'],
|
|
143
|
+
[/^glpat-[A-Za-z0-9_-]{16,}/, 'a GitLab token'],
|
|
144
|
+
[/^(sk|rk)_(live|test)_[A-Za-z0-9]{16,}/, 'a Stripe key'],
|
|
145
|
+
[/^whsec_[A-Za-z0-9+/=]{16,}/, 'a webhook signing secret'],
|
|
146
|
+
[/^xox[abposr]-[A-Za-z0-9-]{10,}/, 'a Slack token'],
|
|
147
|
+
[/^sk-[A-Za-z0-9_-]{20,}/, 'an API secret key'],
|
|
148
|
+
[/^AKIA[0-9A-Z]{16}$/, 'an AWS access key'],
|
|
149
|
+
[/^eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/, 'a signed JSON Web Token'],
|
|
150
|
+
]
|
|
151
|
+
|
|
152
|
+
/** Shannon entropy in bits per character. */
|
|
153
|
+
const entropy = (text: string): number => {
|
|
154
|
+
const counts = new Map<string, number>()
|
|
155
|
+
for (const character of text) counts.set(character, (counts.get(character) ?? 0) + 1)
|
|
156
|
+
let bits = 0
|
|
157
|
+
for (const count of counts.values()) {
|
|
158
|
+
const share = count / text.length
|
|
159
|
+
bits -= share * Math.log2(share)
|
|
160
|
+
}
|
|
161
|
+
return bits
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/** The share of `text` that matches `pattern`, a single-character class. */
|
|
165
|
+
const share = (text: string, pattern: RegExp): number => (text.match(pattern)?.length ?? 0) / text.length
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* A random-looking single word: at least 24 characters of a token alphabet, at least a fifth of them upper case and a
|
|
169
|
+
* fifth lower case, and at least 4 bits of entropy per character. A camel-case name has far fewer capitals than a
|
|
170
|
+
* random string. Hexadecimal (a digest, a UUID) has one letter case and at most 4 bits, so it never matches: a hex
|
|
171
|
+
* credential is caught by its name or not at all.
|
|
172
|
+
*/
|
|
173
|
+
const looksRandom = (text: string): boolean =>
|
|
174
|
+
text.length >= 24
|
|
175
|
+
&& /^[A-Za-z0-9+/=_-]+$/.test(text)
|
|
176
|
+
&& share(text, /[A-Z]/g) >= 0.2
|
|
177
|
+
&& share(text, /[a-z]/g) >= 0.2
|
|
178
|
+
&& entropy(text) >= 4
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* The literal part of a value: references removed, and an Authorization scheme left standing alone by that removal
|
|
182
|
+
* (`Bearer ${token}`) dropped with them.
|
|
183
|
+
*/
|
|
184
|
+
const literalOf = (value: string): string => withoutReferences(value).trim().replace(/^(Basic|Bearer|Token)$/i, '')
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* A setting's value, unwrapped from how a response header is written in `zerops.yaml` (`"'true' always"`): surrounding
|
|
188
|
+
* quotes and nginx's trailing `always` removed.
|
|
189
|
+
*/
|
|
190
|
+
const settingOf = (literal: string): string => {
|
|
191
|
+
let text = literal.replace(/\s+always$/i, '').trim()
|
|
192
|
+
for (let round = 0; round < 2; round++) text = text.replace(/^(['"])(.*)\1$/, '$2').trim()
|
|
193
|
+
return text
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/** A boolean is never a credential, whatever the name says (`Access-Control-Allow-Credentials: true`). */
|
|
197
|
+
const isBoolean = (setting: string): boolean => /^(true|false|yes|no|on|off)$/i.test(setting)
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* A short integer, a decimal or a duration: what a setting that only describes a credential holds (`TOKEN_EXPIRES_IN`,
|
|
201
|
+
* `KEY_ROTATION_DAYS`). It counts only when a word after the credential word names a quantity: `DB_PASSWORD=1234` and
|
|
202
|
+
* `DB_PASSWORD_PROD=1234` are a PIN, and an integer of six digits or more counts anywhere.
|
|
203
|
+
*/
|
|
204
|
+
const isQuantity = (setting: string): boolean => /^(\d{1,5}|\d+\.\d+|\d+(ms|s|m|h|d))$/i.test(setting)
|
|
205
|
+
|
|
206
|
+
/** Words that make a name after its credential word a quantity: `TOKEN_EXPIRES_IN`, `KEY_ROTATION_DAYS`, `PASS_RATE`. */
|
|
207
|
+
const QUANTITY_WORDS: ReadonlySet<string> = new Set([
|
|
208
|
+
'EXPIRES',
|
|
209
|
+
'EXPIRY',
|
|
210
|
+
'IN',
|
|
211
|
+
'AGE',
|
|
212
|
+
'LIFE',
|
|
213
|
+
'LIFETIME',
|
|
214
|
+
'TTL',
|
|
215
|
+
'ROTATION',
|
|
216
|
+
'DAYS',
|
|
217
|
+
'HOURS',
|
|
218
|
+
'MINUTES',
|
|
219
|
+
'SECONDS',
|
|
220
|
+
'INTERVAL',
|
|
221
|
+
'PERIOD',
|
|
222
|
+
'WINDOW',
|
|
223
|
+
'RATE',
|
|
224
|
+
'THRESHOLD',
|
|
225
|
+
'RATIO',
|
|
226
|
+
'MIN',
|
|
227
|
+
'MAX',
|
|
228
|
+
'LENGTH',
|
|
229
|
+
'SIZE',
|
|
230
|
+
'COUNT',
|
|
231
|
+
'LIMIT',
|
|
232
|
+
'RETRIES',
|
|
233
|
+
'ATTEMPTS',
|
|
234
|
+
'TIMEOUT',
|
|
235
|
+
])
|
|
236
|
+
|
|
237
|
+
/** Whether a word after the credential word that matched names a quantity. */
|
|
238
|
+
const describesAQuantity = (words: readonly string[], word: string): boolean => {
|
|
239
|
+
const at = words.indexOf(word === 'BASIC_AUTH' ? 'AUTH' : word)
|
|
240
|
+
return at !== -1 && words.slice(at + 1).some((after) => QUANTITY_WORDS.has(after))
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
/** What the VALUE alone says, or null. Never echoes it. */
|
|
244
|
+
const valueFinding = (literal: string, publicValue: boolean): string | null => {
|
|
245
|
+
if (literal === '') return null
|
|
246
|
+
if (/-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(literal)) return 'it holds a private key'
|
|
247
|
+
if (/^(Basic|Bearer|Token)\s+\S{8,}$/i.test(literal)) return 'it is an Authorization header value'
|
|
248
|
+
// `scheme://user:password@host`: a password in the URL's userinfo. A reference in the password was removed above.
|
|
249
|
+
if (/^[a-z][a-z0-9+.-]*:\/\/[^/@:\s]*:[^/@\s]+@/i.test(literal)) return 'its URL carries a password'
|
|
250
|
+
for (const [pattern, kind] of TOKEN_PREFIXES) {
|
|
251
|
+
if (pattern.test(literal)) return `it reads like ${kind}`
|
|
252
|
+
}
|
|
253
|
+
if (!publicValue && looksRandom(literal)) return 'it is a long random string'
|
|
254
|
+
return null
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
/**
|
|
258
|
+
* Whether a plain `name = value` looks like a credential, and why; null when it does not.
|
|
259
|
+
*
|
|
260
|
+
* The name matches on a credential word (`TOKEN`, `SECRET`, `PASSWORD`, `PASS`, `BASIC_AUTH`, a `KEY` or `KEYS` that is
|
|
261
|
+
* not an id, a public key or a cache key), unless its last word makes it describe one (`TOKEN_URL`,
|
|
262
|
+
* `PASSWORD_MIN_LENGTH`). A name match needs a literal that could be a credential: an empty value, one made only of
|
|
263
|
+
* references or a boolean is not, nor a short number or duration under a name that says it is a quantity. The value matches on its own: a private key, an
|
|
264
|
+
* Authorization header, a URL with a password, an issuer's token prefix, or a long random string unless the name says
|
|
265
|
+
* the value is public (a publishable or site key, an id).
|
|
266
|
+
*/
|
|
267
|
+
export function plainCredentialFinding(name: string, value: string): PlainCredentialFinding | null {
|
|
268
|
+
const words = nameWords(name)
|
|
269
|
+
const literal = literalOf(value)
|
|
270
|
+
const word = credentialWordIn(words)
|
|
271
|
+
const setting = settingOf(literal)
|
|
272
|
+
const describes = isBoolean(setting) || (word !== null && isQuantity(setting) && describesAQuantity(words, word))
|
|
273
|
+
if (word !== null && literal !== '' && !describes) {
|
|
274
|
+
return { basis: 'name', because: `its name contains \`${word}\`` }
|
|
275
|
+
}
|
|
276
|
+
const because = valueFinding(literal, namesAPublicValue(words))
|
|
277
|
+
return because === null ? null : { basis: 'value', because }
|
|
278
|
+
}
|