@oxy-hq/cli 0.5.0 → 0.7.0

package/template/.github/workflows/publish.yaml

@@ -20,29 +20,40 @@
 # scaffolded repo should behave like that on day one rather than arriving with a
 # long-lived credential requirement nobody asked for.
 #
-# The switch is EXPLICIT rather than inferred from the token, and that is the
-# design rather than a preference. Skipping whenever no OXY_TOKEN reached the
-# job would be one line, and it would make "this repo does not publish from CI"
-# indistinguishable from "somebody forgot production's token" — the second of
-# which would then ship nothing, quietly, for as long as nobody looked. With the
-# switch ON a missing token is the loud failure it has always been, which is the
-# property the separate states exist to keep. The reasoning, and why it is a
-# variable and not a secret, is in `.github/scripts/ci-publish.sh`.
+# The switch is EXPLICIT rather than inferred from a credential, and that is
+# the design rather than a preference. Skipping whenever the job could not
+# authenticate would be one line, and it would make "this repo does not publish
+# from CI" indistinguishable from "somebody forgot production's trust policy" —
+# the second of which would then ship nothing, quietly, for as long as nobody
+# looked. With the switch ON a run that cannot authenticate is a loud failure,
+# which is the property the separate states exist to keep. The reasoning, and
+# why it is a variable and not a secret, is in `.github/scripts/ci-publish.sh`.
 #
 # Deliberately NOT modelled on pokehouse-oxy's `franchise-report-app.yml`
 # (Docker -> ECR -> ArgoCD). That is the only real, green CI on disk in this
 # org, which is exactly what makes it tempting; it is a legacy path for the
 # one app still on Next.js and has nothing to do with `oxyc publish`.
 #
-# Auth is a static `OXY_TOKEN` secret, not GitHub OIDC trusted publishing.
-# Both appear in this org's examples and a workflow that MIXES them 403s.
-# OIDC also needs a one-time publisher-registration POST that nothing
-# automates — a manual onboarding step this scaffold exists to remove.
+# AUTH IS GITHUB OIDC BY DEFAULT: NO STORED SECRET. The publish job holds
+# `id-token: write`, and `oxyc publish` trades the job's OIDC token for a
+# fifteen-minute Oxy token acting as a service account, which it revokes when
+# the command ends. What makes the deployment honour that is a TRUST POLICY on
+# the service account, naming this repository, this workflow file
+# (`.github/workflows/publish.yaml`) and the job's `environment:` — one policy
+# per environment, each granted publishing the apps here. An org admin registers
+# it once, in the web app under Organization settings -> Service accounts ->
+# Trusted access; "Publishing custom apps" in README.md has the steps.
+#
+# A STATIC `OXY_TOKEN` SECRET IS THE FALLBACK, and it wins when it is set: a
+# repo that already publishes with one keeps doing exactly that, and a
+# deployment without trusted access has no other way. It is one or the other
+# per run, never a mix — with `OXY_TOKEN` set, no OIDC token is requested.
 #
 # TWO JOBS, and the split is the security boundary, not a style choice.
 # `build` runs the bundles' own postinstall and build scripts — arbitrary
 # third-party code out of node_modules — and holds no publish credential.
-# `publish` holds `OXY_TOKEN`, downloads what `build` produced, and runs no
+# `publish` holds the credential — the `id-token` permission, or the fallback
+# `OXY_TOKEN` — downloads what `build` produced, and runs no
 # package script at all. That includes Oxy Functions: `build` bundles them with
 # `oxyc publish --build-only`, and `publish` runs `oxyc publish --prebuilt`,
 # which checks they arrived rather than running esbuild — so the credential and
@@ -60,9 +71,10 @@
 # fails rather than falling through to the more dangerous of the two.
 #
 # The same resolved name does two jobs: it is the `--env` passed to the CLI AND
-# the GitHub `environment:` the publish job runs in, which is where that env's
-# own `OXY_TOKEN` lives. So the credential and the destination cannot disagree
-# — a production publish can only ever be made with production's token. It is
+# the GitHub `environment:` the publish job runs in — the environment a trust
+# policy is bound to, and where the fallback `OXY_TOKEN` for that env lives. So
+# the credential and the destination cannot disagree — a production publish can
+# only ever be made by a run production's policy (or token) covers. It is
 # resolved ONCE, by `.github/scripts/publish-env.sh` in the `build` job, and
 # read twice; a job's `environment:` can read `needs`, so that is the only
 # place a single value can reach both consumers.
@@ -141,7 +153,14 @@ env:
   # validate.yaml's `OXY_VERSION`: that one is the Rust `oxy` that validates the
   # workspace, a different tool on a different release line. `--build-only` and
   # `--prebuilt`, which the two jobs below depend on, arrived in 0.4.0.
-  OXYC_VERSION: "0.4.0"
+  #
+  # THE PIN DECIDES WHICH OIDC REGISTRATION THE PUBLISH JOB CAN USE. Through
+  # 0.6.0, `oxyc publish` knows one exchange: the app's own registered
+  # publisher (`/api/customer-apps/<app-id>/publishers`). Trust policies on a
+  # service account are honoured from 0.7.0, which tries them first and falls
+  # back to the publisher. A pin older than that still publishes, through the
+  # publisher alone.
+  OXYC_VERSION: "0.7.0"
 
 jobs:
   build:
@@ -404,15 +423,17 @@ jobs:
     # The gate, and the credential boundary. `dev` on a push, `production` on
     # a manual dispatch — the SAME string this job passes to `oxyc publish
     # --env` below, resolved once in `build`, so the destination this job
-    # publishes to and the environment it draws its secrets from are the same
-    # thing by construction. Each environment holds its own `OXY_TOKEN`, and a
-    # missing one is caught explicitly below rather than sent as an empty
-    # bearer.
+    # publishes to and the environment it authenticates as are the same thing
+    # by construction. The environment's name is a claim in the job's OIDC
+    # token, so a trust policy registered for `production` cannot be satisfied
+    # by a run in `dev`; and where the fallback is in use, each environment
+    # holds its own `OXY_TOKEN`.
     #
     # The one hole, and it is a human's to close rather than this file's: a
     # repository-level `OXY_TOKEN`, if one exists, is still reachable here —
     # environment secrets take PRECEDENCE over repository secrets, they do not
-    # exclude them. See the note on `OXY_TOKEN` in the publish step.
+    # exclude them — and a token that is set wins over OIDC. See the note on
+    # `OXY_TOKEN` in the publish step.
     #
     # Referencing an environment that does not exist CREATES it on the first
     # run ("Running a workflow that references an environment that does not
@@ -426,6 +447,17 @@ jobs:
     # need GitHub Team or Pro; oxy-hq is on Team.
     environment: ${{ needs.build.outputs.publish-env }}
 
+    # `id-token: write` lets this job ask GitHub for a signed statement of what
+    # it is — repository, workflow file, environment — which is the whole
+    # credential on the default path. It grants nothing in the repository, and
+    # it is job-level: every step below can use it, which is why this job runs
+    # no package script. `contents: read` is restated because a job-level
+    # `permissions` block REPLACES the workflow-level one rather than adding to
+    # it. The `build` job is deliberately not given the token.
+    permissions:
+      id-token: write
+      contents: read
+
     steps:
       - uses: actions/checkout@v4
         with:
@@ -434,8 +466,8 @@ jobs:
           # bundle built from one commit while claiming another is precisely
           # the confusion the build id exists to prevent.
           ref: ${{ needs.build.outputs.sha }}
-          # This job holds OXY_TOKEN. It has no reason to also be holding a
-          # repository credential in .git/config.
+          # This job holds the publish credential. It has no reason to also be
+          # holding a repository credential in .git/config.
           persist-credentials: false
 
       - uses: actions/download-artifact@v4
@@ -492,6 +524,14 @@ jobs:
 
       - name: Publish each bundle
         env:
+          # THE FALLBACK CREDENTIAL, empty unless somebody set the secret. With
+          # it empty — the default — `oxyc publish` exchanges this job's OIDC
+          # token instead and nothing is stored anywhere. With it set, it WINS:
+          # no OIDC token is requested, and the run authenticates exactly as it
+          # did before OIDC was the default. Any kind of Oxy token works here —
+          # a service account token (`oxy_sat_…`), a personal access token
+          # (`oxy_pat_…`), or a workspace API key from before either existed.
+          #
           # Step-scoped as well as job-isolated. The job split is what keeps
           # this token away from the bundles' own build scripts — those ran
           # in `build`, on a different runner, and nothing in THIS job runs a
@@ -509,15 +549,27 @@ jobs:
           # precedence, not exclusion: an environment secret OVERRIDES a
           # repository one of the same name, it does not suppress it. So a
           # repo still carrying an old repository-level `OXY_TOKEN` serves
-          # BOTH environments from it wherever the environment has none — the
-          # guard below never fires, and each publish looks perfectly healthy
-          # while authenticating with a token nobody scoped to it.
+          # BOTH environments from it wherever the environment has none — OIDC
+          # is never tried, and each publish looks perfectly healthy while
+          # authenticating with a token nobody scoped to it.
           #
           # Nothing here can catch that: GitHub does not tell a job which
           # level a secret came from, so from inside this step the two cases
           # are identical. It has to be a human, once: DELETE any
-          # repository-level `OXY_TOKEN` after adding the environment ones.
+          # repository-level `OXY_TOKEN` — after registering the trust policies
+          # (or adding the environment-level tokens) that replace it. The step
+          # below prints which of the two credentials it used, every run.
           OXY_TOKEN: ${{ secrets.OXY_TOKEN }}
+          # The ID of the service account the OIDC exchange acts as — from the
+          # account's page under Organization settings → API access. REQUIRED
+          # for a trust policy to be used: the deployment matches this run
+          # against that one account's policies and never picks an account on
+          # a run's behalf. Unset, the publish goes through each app's
+          # registered publisher instead. The ID, never `<org-slug>/<name>`: a
+          # name can be taken over by another organization, an ID cannot.
+          # Unused on the `OXY_TOKEN` path. An ENVIRONMENT variable where
+          # `dev` and `production` use different accounts.
+          OXY_SERVICE_ACCOUNT: ${{ vars.OXY_SERVICE_ACCOUNT }}
           # `dev` or `production`, resolved once in the build job. Passed to
           # `oxyc publish --env` below; the identical string selected the
           # environment this job is running in.
@@ -552,8 +604,28 @@ jobs:
             exit 1
           fi
 
-          if [ -z "${OXY_TOKEN:-}" ]; then
-            echo "::error::no OXY_TOKEN reached this job, so there is nothing to authenticate with. Neither the '$PUBLISH_ENV' environment nor the repository holds one — an environment secret takes precedence over a repository secret of the same name, so this fires only when both are absent. Mint a publish-scoped API key in oxy and add it under Settings -> Environments -> $PUBLISH_ENV -> Environment secrets, NOT at repository level: a repository-level token would serve both environments and this check could never tell you." >&2
+          # Which credential this run uses, said out loud on every run — the
+          # two paths fail differently, and "which one was it" should never
+          # need working out from a stack of 403s.
+          if [ -n "${OXY_TOKEN:-}" ]; then
+            echo "authenticating with the OXY_TOKEN secret (the fallback path). To publish with no stored secret instead, register a trust policy for the '$PUBLISH_ENV' environment and delete the secret — see 'Publishing custom apps' in README.md."
+            # A service account is chosen by the OIDC exchange only; leaving
+            # the variable set would be a setting that silently does nothing.
+            unset OXY_SERVICE_ACCOUNT
+          elif [ -n "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ]; then
+            echo "authenticating with this job's GitHub OIDC token — no stored secret. oxyc exchanges it for a fifteen-minute token on each publish and revokes that token when the command ends."
+            # An unset secret arrives as an EMPTY variable, not a missing one.
+            # oxyc treats the two alike; unsetting it says so here too.
+            unset OXY_TOKEN
+            if [ -z "${OXY_SERVICE_ACCOUNT:-}" ]; then
+              unset OXY_SERVICE_ACCOUNT
+              echo "no OXY_SERVICE_ACCOUNT variable on the '$PUBLISH_ENV' environment: each app publishes through its registered publisher. To use a trust policy, set the variable to the service account's ID."
+            fi
+          else
+            # Reachable only if this job lost `id-token: write` — an edit to
+            # the `permissions` block above, or an org policy that withholds
+            # it. Fail here, by name, rather than as oxyc's "not authenticated".
+            echo "::error::this job has nothing to authenticate with: GitHub issued it no OIDC token and no OXY_TOKEN secret is set. The publish job needs 'permissions: id-token: write' (see the job's permissions block), and a trust policy registered for the '$PUBLISH_ENV' environment — or, as the fallback, an OXY_TOKEN secret under Settings -> Environments -> $PUBLISH_ENV -> Environment secrets, NOT at repository level." >&2
             exit 1
           fi
 

package/template/README.md

@@ -201,11 +201,11 @@ stops publishing with nobody told, and guessed as on publishes when nobody
 asked, so it is not guessed.
 
 Note what the switch does **not** do. It decides whether the publish job runs;
-it never softens what happens once it has. With CI publishing on, a missing
-`OXY_TOKEN` is a **hard failure** exactly as it always was. That is the reason
-there is a switch at all rather than the obvious shortcut of skipping whenever
-no token turns up: inferred from the token, "this repo does not publish from
-CI" and "somebody forgot production's token" are the same observation — and
+it never softens what happens once it has. With CI publishing on, a run that
+cannot authenticate is a **hard failure**. That is the reason there is a switch
+at all rather than the obvious shortcut of skipping whenever no credential
+turns up: inferred from the credential, "this repo does not publish from CI"
+and "somebody forgot production's trust policy" are the same observation — and
 the second one ships nothing, quietly, for as long as nobody looks.
 
 Everything from here to the end of this section describes a repo that has
@@ -241,9 +241,10 @@ is no code path that can fall back to a default.
 
 There is deliberately **no environment picker** on the manual run. An input
 would need a default, which is the thing being removed; and the same resolved
-name also selects the GitHub environment whose `OXY_TOKEN` the job publishes
-with, so leaving it to a form field would mean the credential and the
-destination agree only by an operator's care. To publish a dev draft by hand,
+name also selects the GitHub environment the job runs in — which is what its
+credential is bound to — so leaving it to a form field would mean the
+credential and the destination agree only by an operator's care. To publish a
+dev draft by hand,
 re-run the push-triggered run from the Actions tab — a re-run keeps the
 original event, so it still resolves to `dev`.
 
@@ -251,10 +252,10 @@ It is **two jobs**, and the split is the security boundary rather than a
 tidiness one. `build` runs `pnpm install` and `pnpm -r build` — which is to
 say it executes the postinstall and build scripts of every dependency your
 apps pull in — and holds no publish credential at all. It hands the built
-output to `publish` as a workflow artifact. `publish` holds `OXY_TOKEN`, and
-runs no package script: `oxyc publish --dir` uploads a pre-built directory
+output to `publish` as a workflow artifact. `publish` holds the credential,
+and runs no package script: `oxyc publish --dir` uploads a pre-built directory
 as-is instead of building anything. So a compromised dependency in an app's
-tree never runs on a runner where the token exists.
+tree never runs on a runner where the credential exists.
 
 **On a fresh repo it does nothing at all, and that is the intended
 behaviour.** The scaffold ships no apps and no `pnpm-lock.yaml` — there is
@@ -264,32 +265,90 @@ the run goes **green**. The install is skipped along with the publish
 deliberately: `pnpm install --frozen-lockfile` fails without a lockfile, and
 a repo whose CI is red the day it is created is a repo where nobody reads CI.
 
-Before it can publish anything, each of the two **GitHub environments** —
-`dev` and `production` — needs its own **`OXY_TOKEN`** (Settings →
-Environments → *environment* → Environment secrets), a publish-scoped API key
-minted in oxy against that workspace. This is the credential the self-serve
-model does without, and it is worth knowing what it is before you create one:
-a personal API key records the project it was minted against, but that project
-never reaches validation — a leaked key carries the minter's **user-level**
-access, not "this app's project only".
-
-**A missing one fails the run, loudly, and that is the intended behaviour.**
-It is also why CI publishing is a switch rather than something inferred from
-the token's presence: with the switch on, no token means a red run naming the
-environment it was looked for in, never a green run that published nothing.
+#### How CI authenticates: no stored secret
+
+**By default the publish job holds no secret at all.** It is granted
+`id-token: write`, which lets it ask GitHub for a signed statement of what it
+is — this repository, this workflow file, the environment the job runs in.
+`oxyc publish` hands that statement to oxy and gets back a token that lasts
+fifteen minutes, acts as a **service account** of your organization, and is
+revoked when the command ends. There is nothing to rotate and nothing to leak
+from Settings.
+
+What makes oxy honour the statement is a **trust policy** on the service
+account, and it has to exist before the first publish. An org admin registers
+one **per environment**, once:
+
+1. In the web app: **Organization settings → API access → Service accounts**.
+   Create a service account — `deployer` is the conventional name — with the
+   role *member*.
+2. Open it and, under **Trusted access**, add a policy for each of `dev` and
+   `production`:
+
+   | Field | Value |
+   | --- | --- |
+   | Repository | this repo, as `<owner>/<repo>` |
+   | Workflow | `.github/workflows/publish.yaml` |
+   | Environment | `dev` (and a second policy for `production`) |
+   | Grant | publishing the apps under `apps/` — and nothing else |
+
+The environment is part of the match, so the `production` policy cannot be
+satisfied by a push-triggered run in `dev`: the credential and the destination
+agree by construction, exactly as they did when each environment held its own
+token. A run no policy matches fails with the repository, workflow and ref it
+presented, which is usually enough to see which field is off.
+
+**Name the account the workflow acts as, by its ID**, in an
+`OXY_SERVICE_ACCOUNT` **variable** on the environment. The ID is on the
+account's page (Organization settings → API access → Service accounts → the
+account). It is required for a trust policy to be used at all: the deployment
+matches a run against the policies of the one account its workflow names, and
+never picks one on a run's behalf — anyone can register a policy that names a
+repository. With the variable unset, the publish goes through each app's
+*registered publisher* instead, as it did before trust policies existed.
+
+The ID, never `<org-slug>/<name>`: a slug is free for anyone once its org
+renames or is deleted, so a name can be taken over and an ID cannot. A name in
+the variable is refused (`service_account_required`).
+
+> Trust policies need a recent enough CLI in CI. The workflow pins the one it
+> installs as `OXYC_VERSION`; the comment beside the pin says which release
+> first honours them. An older pin still publishes with no stored secret, but
+> only through an app's *registered publisher* — the earlier, per-app
+> registration (`/api/customer-apps/<app-id>/publishers`), which Oxy staff set
+> up.
+
+#### The fallback: an `OXY_TOKEN` secret
+
+A static token still works, and **when it is set it wins** — the job then
+requests no OIDC token and authenticates exactly as this workflow always did.
+Use it where the deployment has no trusted access yet, or where a repository
+cannot be given a trust policy. Each of the two **GitHub environments** — `dev`
+and `production` — holds its own **`OXY_TOKEN`** (Settings → Environments →
+*environment* → Environment secrets). Prefer a **service account token**
+(Organization settings → API access → Service accounts → *account* → Tokens),
+granted only what publishing needs; a personal access token or an older
+workspace API key also works, and carries its owner's access with it — a
+leaked one is that person, not "this app only".
+
+Every run prints which of the two it used. **A run with neither fails,
+loudly, and that is the intended behaviour.** It is also why CI publishing is
+a switch rather than something inferred from a credential's presence: with the
+switch on, a job that cannot authenticate is a red run that says why, never a
+green run that published nothing.
 
 **And any repository-level `OXY_TOKEN` must be DELETED, not left in place.**
 GitHub's order is environment → repository → organisation, and that is
 *precedence, not exclusion*: an environment secret overrides a repository one
 of the same name, it does not suppress it. A repo still carrying an old
 repository-level token therefore serves **both** environments from it wherever
-the environment has none — every run looks healthy, the missing-token check
-never fires, and production ships under whatever that token was scoped to.
+the environment has none — every run looks healthy, OIDC is never tried, and
+production ships under whatever that token was scoped to.
 
 Nothing in CI can catch it. GitHub does not tell a job which level a secret
 came from, so the two cases are identical from inside the run. It is a
 one-time human check, and it is the single thing to get right when moving an
-existing repo onto environments:
+existing repo onto trust policies or onto environments:
 
 ```bash
 gh secret list --repo <owner>/<repo>              # repository level
@@ -311,10 +370,13 @@ So adding the first app is two things — three, if this repo publishes from CI:
    lockfile it writes. Only the lockfile: `node_modules/` and every app's
    build output are covered by `.gitignore`, so `git add -A` after an install
    stages the one file CI needs and none of the ones it does not;
-3. **only with `OXY_CI_PUBLISH` set** — an `OXY_TOKEN` in each environment.
+3. **only with `OXY_CI_PUBLISH` set** — a trust policy for each environment
+   that grants publishing the app (or, as the fallback, an `OXY_TOKEN` in each
+   environment).
 
 Miss one and the workflow fails loudly and names it: the discovery step
-points at the manifest, or the missing lockfile, or the missing secret. It
+points at the manifest, or the missing lockfile; the publish step says no
+trust policy matched the run, or that it had nothing to authenticate with. It
 does not guess and it does not half-publish. (The first two are needed even
 with CI publishing off: the `build` job installs and builds either way.)
 
@@ -397,8 +459,10 @@ someone points each at the branch:
 
 Promoting the production semantic model is a deliberate, human step: open the
 production workspace in Oxygen and pull the latest commit. **CI does not do
-it**, and holds no credential that could — the `OXY_TOKEN` in each environment
-is publish-scoped and cannot compile or promote a workspace at all. So a merge
+it**, and holds no credential that could — the trust policy behind each
+environment grants publishing apps and nothing else, so the token the job is
+handed cannot compile or promote a workspace at all. (Keep it that way on the
+fallback path: an `OXY_TOKEN` should be a token that can only publish.) So a merge
 to `main` never changes what production answers until someone decides it
 should.