Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
7658ab7
microVM JIT mint on the host and attempt-owned jail staging
Sep 19, 2026
3341ce9
Address review 68117: ByteSize carrier, one JWT claim/header authorit…
Sep 19, 2026
0e26b37
Address review 68156: EpochSecs for the JWT clock, delete planned_jit…
Sep 19, 2026
afcc701
extdeps.tools.openssl: import Unit from std.types (floor AmbiguousBar…
Sep 19, 2026
be8da16
runner_attempt_launch: derive the jit device's install mode and readb…
Sep 19, 2026
4830553
App JWT carried as extdeps.auth.jwt JwtCompactSerialization, not a ba…
Sep 19, 2026
2fc768a
github_effect_perform: hoist the brand-shedding note out of the funct…
Sep 19, 2026
e20ac1c
Reconcile the RS256 'cannot sign' rows with the signer this PR lands;…
Sep 19, 2026
bb09595
Merge origin/main (#11674 registration labels) into #11677; drop driv…
Sep 19, 2026
da1f422
Merge origin/main (#11547 generic App-token prelude) into #11677; the…
Sep 19, 2026
9580ef2
Model the signer over a key reference (extdeps.auth.jws JwsSigningKey…
Sep 19, 2026
43da036
Merge origin/main (#11671); stage exactly runner_microvm jit_drive_co…
Sep 19, 2026
8185db2
Refuse a mint whose App is not the one the controller key belongs to …
Sep 19, 2026
f875cd1
Measure the credential in bytes, and delete the dangling endpoint_pat…
Sep 19, 2026
f8fe885
Merge origin/main (#11671 guest bootstrap, #11675 guest network + wor…
Sep 20, 2026
ea738ca
Merge branches 'main' and 'session/keen-bear-791' of https://github.c…
Sep 20, 2026
e6cef61
Staging admits the jailer only from BOTH stagings, through a sealed r…
Sep 20, 2026
0da0882
Merge origin/main (#11672 microVM shape, #11675 workspace staging, gh…
Sep 20, 2026
46a9c33
stat.dag: restore the brace my keep-both merge resolution cut (floor:…
Sep 20, 2026
7a9a379
Take main's generated workflow projections; my copies were stale gene…
Sep 20, 2026
a6ed2fd
chore: regenerate drifted generated artifacts (ci auto-heal)
gunbai-bot[bot] Sep 20, 2026
12c0ffc
Merge main into the #11677 base for the wet lifecycle controller lane
Sep 20, 2026
8891230
microVM: carry the staged credential device path on InFlightAttempt, …
Sep 20, 2026
ec2973a
Merge origin/main (#11791 fleet witness lane + drift gate) into #11677
Sep 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 89 additions & 0 deletions dag/extdeps/auth/jws.dag
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
module extdeps.auth.jws

import std.types { String, NonEmptyStr, Int, List }
import std.integer { UInt8 }
import std.bytes { bytes_octets, utf8_encode_bytes }
import std.encoding { base64_encode, UrlSafe }
import std.decl_ref { DeclarationRef, WholeDeclaration }
import extdeps.external_authority { ExternalAuthority, ExternalModelScope, ExternalSubjectRef }
import extdeps.uri { Uri, Https }
import extdeps.auth.jwt { JwtCompactSerialization }

data extdeps_external_authority_anchor: ExternalAuthority = ExternalAuthority {
uri: Uri { scheme: Https, locator: "datatracker.ietf.org/doc/html/rfc7515" }
}

data jwa_rs256_citation: ExternalAuthority = ExternalAuthority {
uri: Uri { scheme: Https, locator: "datatracker.ietf.org/doc/html/rfc7518#section-3.3" }
}

// THIS MODULE IS THE SHAPE OF A COMPACT JWS AND NOTHING ELSE. It produces the JWS Signing Input
// (RFC 7515 section 5.1 step 5: BASE64URL(UTF8(protected header)) '.' BASE64URL(payload)) and joins
// a signature the CALLER obtained onto it (section 7.1). It does not sign: the signature is a
// private-key operation, and which realization performs it -- a host CLI, an HSM, a library -- is a
// transport bound to this shape, never a fact about JWS (DESIGN §3). extdeps.auth.jwt describes
// claims and does not verify them; this module is the other direction and does not verify either.
//
// ONE ALGORITHM, RS256, because one is what this fleet signs with. RFC 7518 registers many;
// modeling ones no realization produces would be vocabulary with no consumer (DESIGN §3c). When a
// second signer lands, this row becomes an algorithm coproduct and the functions take it.
data jws_rs256_alg: NonEmptyStr = "RS256"

// BASE64URL IS RFC 7515 section 2's: the URL-safe alphabet of RFC 4648 section 5 WITH ALL TRAILING
// '=' OMITTED. std.encoding pads, so the padding is cut here rather than a second encoder written.
fn jws_base64url_octets(octets: List<UInt8>) -> String {
join(split(s: base64_encode(octets: octets, variant: UrlSafe), delimiter: "="), "")
}

fn jws_base64url_text(s: String) -> String {
jws_base64url_octets(octets: bytes_octets(b: utf8_encode_bytes(s: s)))
}

fn jws_rs256_protected_header_json() -> String {
join(["\{\"alg\":\"", jws_rs256_alg as String, "\",\"typ\":\"JWT\"}"], "")
}

fn jws_rs256_signing_input(payload_json: String) -> NonEmptyStr {
join([
jws_base64url_text(s: jws_rs256_protected_header_json()),
".",
jws_base64url_text(s: payload_json),
], "") as NonEmptyStr
}

// THE SIGNER INTERFACE: sign(signing input, key reference) -> signature octets. Its SUBJECT is the
// KEY CUSTODY BOUNDARY -- a private key that must not enter the evaluator -- which is what makes a
// host realization honest here (PRIMITIVE-EGRESS-0 ruling, fierce-seal-607: a signer on an external
// key is a bound host effect; "RSA realized by a CLI" would be an ambient primitive). So the key is
// named by REFERENCE and never carried as bytes, and the outcome is octets or a located refusal.
// Handlers bind to this shape (extdeps.tools.openssl is one); the dispatch that selects a handler is
// realization and lives peripheral, in gunbc.jws_signer_realize, never here (DESIGN §3).
type JwsSigningKeyRef
= HostKeyFile { path: NonEmptyStr }

type JwsSignOutcome
= JwsSigned { signature: List<UInt8> }
| JwsSignRefused { detail: String }

// THE SIGNATURE IS OCTETS, NOT TEXT. A realization that hands back a printable rendering (hex,
// standard base64) decodes it to octets first; this join then encodes exactly once. Accepting a
// pre-encoded String here would let a standard-alphabet signature through looking valid.
//
// THE RESULT IS extdeps.auth.jwt JwtCompactSerialization, not a bare string: the only protected
// header this module produces is typ JWT, so every value it emits IS a JWT, and the brand keeps it
// from being confused with an opaque bearer (an installation token is not decodable).
fn jws_compact_serialization(signing_input: NonEmptyStr, signature: List<UInt8>) -> JwtCompactSerialization {
join([signing_input as String, ".", jws_base64url_octets(octets: signature)], "") as JwtCompactSerialization
}

data extdeps_model_scope: ExternalModelScope = ExternalModelScope {
subject: ExternalSubjectRef {
declaration: DeclarationRef {
module_path: "extdeps.auth.jws",
decl_name: "jws_rs256_signing_input",
field: WholeDeclaration
}
},
first_citation: extdeps.auth.jws.extdeps_external_authority_anchor,
further_citations: [extdeps.auth.jws.jwa_rs256_citation]
}
7 changes: 7 additions & 0 deletions dag/extdeps/clock/clock.dag
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,13 @@ fn clock_unix_millis_read() -> ClockUnixMillisRead {
}
}
}

// THE ONE MILLIS-TO-SECONDS CONVERSION, beside the read that produces millis. Truncation toward the
// epoch is POSIX seconds' own rounding (date +%s truncates), and both carriers are non-negative, so
// a reading that satisfied EpochMs yields one that satisfies EpochSecs.
fn epoch_secs_of_millis(millis: EpochMs) -> EpochSecs {
millis / 1000
}
// SAME OUTPUT-SHAPE DISCIPLINE AS clock_unix_millis_read: the operation's
// output stays String, and this typed wrapper parses it with proper refusal.
// Uses EpochSecs (std.types), the same pattern clock_unix_millis_read uses
Expand Down
4 changes: 4 additions & 0 deletions dag/extdeps/exec/command.dag
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,10 @@ fn argv_command(program: NonEmptyStr, arguments: List<String>) -> ArgvCommand
decl_ref(module_path: "extdeps.sudo.elevation", decl_name: "sudo_preserve_environment_command"),
decl_ref(module_path: "extdeps.tools.stat", decl_name: "stat_file_type_command"),
decl_ref(module_path: "extdeps.tools.stat", decl_name: "stat_inode_command"),
decl_ref(module_path: "extdeps.tools.stat", decl_name: "stat_owner_uid_command"),
decl_ref(module_path: "extdeps.tools.stat", decl_name: "stat_mode_command"),
decl_ref(module_path: "extdeps.tools.stat", decl_name: "stat_size_bytes_command"),
decl_ref(module_path: "extdeps.tools.gnu_coreutils", decl_name: "install_empty_file_command"),
decl_ref(module_path: "extdeps.tools.stat", decl_name: "stat_allocated_blocks_command"),
decl_ref(module_path: "extdeps.tools.mkdir", decl_name: "mkdir_parents_command_at"),
decl_ref(module_path: "extdeps.tools.mkdir", decl_name: "mkdir_exact_command_at"),
Expand Down
65 changes: 59 additions & 6 deletions dag/extdeps/github/actions_jit_runner.dag
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
module extdeps.github.actions_jit_runner

import std.types { String, NonEmptyStr, Bool, Int, List, HttpStatus }
import std.types { String, NonEmptyStr, Bool, Int, List, HttpStatus, Secret }
import extdeps.github.github { default_api_base }
import extdeps.transports.rest { RestOutcome }
import extdeps.external_authority { ExternalAuthority }
import extdeps.uri { Uri, Https }

Expand Down Expand Up @@ -71,11 +73,6 @@ type JitConfigMintOutcome
| JitConfigMintConflict { reason: String }
| JitConfigMintValidationFailed { reason: String }

// THE ENDPOINT PATH IS DERIVED FROM THE ORG, never concatenated at a call site, so a caller cannot
// address a different organization's runners by assembling the path itself.
fn org_generate_jitconfig_path(org_login: NonEmptyStr) -> String {
join(["/orgs/", org_login as String, "/actions/runners/generate-jitconfig"], "")
}

fn jit_runner_label_wire(l: JitRunnerLabel) -> String {
l.value as String
Expand Down Expand Up @@ -123,3 +120,59 @@ fn jit_config_mint_outcome(status: HttpStatus, encoded: String, runner_id: Int,
}
}
}

// THE MINT IS ONE OPERATION ON GitHub's REST SURFACE, bound to the shape above. The Bearer is an
// INSTALLATION access token (extdeps.github.app github.AppInstallationAccessTokens), taken as a
// Secret input and never an argv word. The body is JitRunnerConfigRequest's wire: labels arrive as
// the JSON array the endpoint documents, projected by jit_runner_label_wire. 201 decodes the runner
// identity and the opaque blob; every other status is RestStatusRefused and is mapped through
// jit_config_mint_outcome, the one authority for what a non-201 means.
type JitConfigCreatedRunner {
id: Int
}

type JitConfigCreatedBody {
runner: JitConfigCreatedRunner
encoded_jit_config: String
}

// THE ORGANIZATION IS AN OPERATION INPUT AND THE PATH INTERPOLATES IT, so a caller cannot address
// another organization's runners by assembling a path: there is no path to assemble. A builder
// function beside this template would be a second spelling of one endpoint that the transport can
// never call -- the template language interpolates, it does not invoke -- so the citation for this
// path is extdeps_external_authority_anchor above and this operation is its only consumer.
service github.ActionsJitRunners {
config {
endpoint: default_api_base
auth: Bearer
auth_input: installation_token
}

operation GenerateOrganizationJitConfig {
input {
installation_token: Secret
org: NonEmptyStr
name: NonEmptyStr
runner_group_id: Int
labels: List<String>
work_folder: NonEmptyStr
}
output {
result: JitConfigCreatedBody
outcome: RestOutcome
}
transport rest {
method: POST,
path: "/orgs/\{org\}/actions/runners/generate-jitconfig",
body: {
name: name,
runner_group_id: runner_group_id,
labels: labels,
work_folder: work_folder
}
}
response {
201 => JitConfigCreatedBody
}
}
}
53 changes: 47 additions & 6 deletions dag/extdeps/github/app.dag
Original file line number Diff line number Diff line change
Expand Up @@ -1080,8 +1080,10 @@ service github.AppPublicRegistry {
// THE APP-JWT CREDENTIAL IS READ AT THE TRANSPORT FROM THE ENVIRONMENT, NOT TAKEN AS AN OPERATION
// INPUT, following the extdeps.google.sheets and github.Checks precedent and for the reason
// list_app_installations_citation states outright: "You must use a JWT to access this endpoint." That
// JWT is RS256-signed with the App's private key, and NOTHING IN THIS CORPUS CAN SIGN RS256 - verified,
// not assumed. So the minting step is external and hourly (org_admin_auth: iat backdated up to 60s,
// JWT is RS256-signed with the App's private key. The corpus CAN sign one on a host that holds the key
// FILE -- the extdeps.auth.jws signer, realized by gunbc.jws_signer_realize, performed by gunbc.github_effect_perform -- but
// this service's callers (the census and org instruments) run where no key file is custodied, so for
// them the minting step is still external and hourly (org_admin_auth: iat backdated up to 60s,
// exp at most 10 minutes), and the boundary this module holds is that no caller can interpolate a token
// into an argument list: the transport reads GITHUB_APP_JWT or the request goes out unauthenticated and
// upstream refuses it with a status this operation classifies.
Expand Down Expand Up @@ -1200,10 +1202,11 @@ fn installation_from_record(record: GitHubAppInstallationRecord) -> Installation
// GitHubInstallationTokenRequest above carried the narrowing vocabulary and the verdict fold but had
// no spelling of the POST body those narrowings become, so the half of the budget path that IS
// decidable here - what we would ask for, and whether it exceeds the installation - stopped short of
// the wire. The endpoint is named through org_admin_auth's citation-bearing builder rather than
// respelled. There is no operation: the request needs an RS256-signed App JWT, and nothing in this
// corpus can sign one, so declaring an operation would be a route that cannot execute (DESIGN 4b:
// do not cite a check for a red it cannot produce).
// the wire. installation_token_request_url names the endpoint through org_admin_auth's
// citation-bearing builder. The OPERATION is github.AppInstallationAccessTokens below, taking the
// App JWT as an input; its rest path template is necessarily a transport literal (the template
// language interpolates the id into the path, it cannot call a builder), and it names the same
// endpoint -- a divergence of spelling the transport forces, stated rather than hidden.
fn installation_token_request_url(request: GitHubInstallationTokenRequest) -> String {
github_app_installation_access_token_url(installation_id: request.installation_id.value)
}
Expand Down Expand Up @@ -1263,3 +1266,41 @@ data extdeps_model_scope: ExternalModelScope = ExternalModelScope {
extdeps.github.app.webhook_events_citation
]
}

// POST /app/installations/{installation_id}/access_tokens, cited by
// extdeps.github.org_admin_auth installation_token_citation. It authenticates AS THE APP -- the
// Bearer is an RS256 App JWT (extdeps.auth.jws), never an installation or user token -- and answers
// 201 with a token valid for one hour. The token is decoded straight into a Secret so it has no
// String life in this process. A mutation: a transport refusal is commit-ambiguous, and the caller
// classifies it through extdeps.transports.rest classify_rest_outcome as RestMutationExchange.
service github.AppInstallationAccessTokens {
config {
endpoint: default_api_base
auth: Bearer
auth_input: app_jwt
}

operation Create {
input {
app_jwt: Secret
installation_id: Int
}
output {
token: Secret from "token"
outcome: RestOutcome
}
transport rest {
method: POST,
path: "/app/installations/\{installation_id\}/access_tokens",
body: { }
}
response {
201 => GitHubInstallationAccessTokenBody
}
}
}

type GitHubInstallationAccessTokenBody {
token: String
expires_at: String
}
21 changes: 20 additions & 1 deletion dag/extdeps/github/org_admin_auth.dag
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
module extdeps.github.org_admin_auth

import std.types { NonEmptyStr, Timestamp, String, Int }
import std.types { NonEmptyStr, Timestamp, String, Int, EpochSecs }
import std.decl_ref { DeclarationRef, WholeDeclaration }
import extdeps.external_authority { ExternalAuthority, ExternalModelScope, ExternalSubjectRef }
import extdeps.uri { Uri, Https }
Expand Down Expand Up @@ -38,6 +38,25 @@ data github_app_jwt_backdate_seconds: Int = 60

data github_app_jwt_lifetime_seconds: Int = 540

// THE APP JWT'S CLAIMS, as installation_token_citation states them: iss is the App id, iat is
// backdated for clock skew, exp is within ten minutes of issue. ONE authority for the claim SHAPE:
// github_app_jwt_claims_json_of spells the JSON once over rendered values, and both producers go
// through it -- gunbc.github_effect_perform with the numbers themselves, and gunbc.ci_spec's shell
// preludes with printf placeholders their runtime `date +%s` fills (those preludes compute the
// clock in the step that signs, so they cannot take a number from here; the shape and both bounds
// they still can).
fn github_app_jwt_claims_json_of(iat: String, exp: String, iss: String) -> String {
join(["\{\"iat\":", iat, ",\"exp\":", exp, ",\"iss\":\"", iss, "\"}"], "")
}

fn github_app_jwt_claims_json(app_id: Int, now_epoch_secs: EpochSecs) -> String {
github_app_jwt_claims_json_of(
iat: to_string(now_epoch_secs - github_app_jwt_backdate_seconds),
exp: to_string(now_epoch_secs + github_app_jwt_lifetime_seconds),
iss: to_string(app_id),
)
}

data oauth_flow_citation: ExternalAuthority = ExternalAuthority {
uri: Uri { scheme: Https, locator: "docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps" }
}
Expand Down
1 change: 1 addition & 0 deletions dag/extdeps/package_managers/apt.dag
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ data package_curl: NonEmptyStr = "curl"
data package_nbdkit: NonEmptyStr = "nbdkit"
data package_socat: NonEmptyStr = "socat"
data package_sshpass: NonEmptyStr = "sshpass"
data package_openssl: NonEmptyStr = "openssl"
data package_gh: NonEmptyStr = "gh"
data package_mosquitto_clients: NonEmptyStr = "mosquitto-clients"
data package_websocat: NonEmptyStr = "websocat"
Expand Down
12 changes: 12 additions & 0 deletions dag/extdeps/tools/gnu_coreutils.dag
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ data true_program: NonEmptyStr = "true"
data whoami_program: NonEmptyStr = "whoami"
data readlink_program: NonEmptyStr = "readlink"
data ls_program: NonEmptyStr = "ls"
data install_program: NonEmptyStr = "install"

// -1 ALONE, AND THE NAME CARRIES IT FOR THE SAME REASON rm_force_command's DOES. `-1` forces ONE
// ENTRY PER LINE, which is what makes the output splittable by the caller: ls(1) columnates when
Expand All @@ -62,6 +63,17 @@ fn cp_command(source: String, destination: String) -> ArgvCommand {
argv_command(program: cp_program, arguments: [source, destination])
}

// install(1) COPYING /dev/null CREATES AN EMPTY FILE WITH ITS FINAL OWNER AND MODE IN ONE STEP.
// The point is the ORDER it makes possible: a file that will later hold a secret exists with its
// restrictive mode before a single secret byte is written, so there is no window in which the bytes
// sit under the default umask. Mode is an octal spelling because that is what -m documents.
fn install_empty_file_command(path: String, octal_mode: NonEmptyStr, uid: Int, gid: Int) -> ArgvCommand {
argv_command(
program: install_program,
arguments: ["-m", octal_mode as String, "-o", to_string(uid), "-g", to_string(gid), "/dev/null", path],
)
}

// -f ALONE, NEVER -rf, AND THAT IS THE POINT OF THE NAME. -f makes a missing file a success, which
// is what an unlink-if-present means; it does NOT recurse, so a path that turns out to be a
// directory refuses instead of destroying its contents. The recursive form is a different operation
Expand Down
Loading