🔄 Sync shared files from ws-meta

charts/workspace/scripts/env.reference.yaml

@@ -70,6 +70,7 @@ envs:
         type: string
         default: null
         delimiter: ;
+        pattern: "[a-zA-Z0-9 ./:_=~+[\\]-]+"
         reference: /tools/apt
         example: >-
           deb http://one.test trixie main; deb http://two.test trixie main
@@ -107,12 +108,30 @@ envs:
           The workspace ships with a set of preference files that block
           GUI/desktop and other packages that have no use inside a headless
           container *(`x11`, `desktop`, `mail`, `printing`, `daemons`,
-          `language-pack`, `obsolete`)*.
+          `cni`, `language-pack`, `obsolete`)*.
 
           Accepts either:
           - A **space-delimited** list of restriction names.
           - A boolean `true` or `*` value to disable all restrictions.
 
+      override_restrictions:
+        type: boolean
+        default: false
+        since: 0.3.0
+        reference: /tools/apt
+        example: "true"
+        description: Temporarily lifts all APT install restrictions for `additional_packages`.
+        longDescription: |
+          Distinct from `disable_restrictions`, which **permanently** lifts
+          restrictions at startup. This flag applies **only** to the
+          `additional_packages` install step: every active
+          `/etc/apt/preferences.d/99-deny-*` pin is renamed to `.disabled`
+          immediately before the install and restored when it completes
+          *(including on failure)*.
+
+          Set to `true` when an entry in `additional_packages` is blocked by
+          a shipped restriction and a permanent lift is undesirable.
+
       update_cache:
         type: boolean
         default: false
@@ -125,7 +144,7 @@ envs:
       disable_sudo:
         type: boolean
         default: false
-        since: 0.3.0
+        since: 0.0.2
         description: Disables password-less `sudo`.
 
       github_token:
@@ -150,6 +169,158 @@ envs:
              `/run/secrets/workspace/auth/github_token`.
           4. Schema default *(unset)*.
 
+      mode:
+        type: string
+        default: password
+        since: 0.3.1
+        example: oidc
+        description: Web authentication mode, either `password` or `oidc`.
+        reference: /editor/authentication
+        longDescription: |
+          - `password` *(default)*: the editor's built-in password login via
+            `WS_AUTH_PASSWORD` / `WS_AUTH_PASSWORD_HASHED`. Unchanged behaviour.
+          - `oidc`: an in-workspace oauth2-proxy listens on
+            `WS_SERVER_AUTH_PROXY_PORT` and authenticates every request against
+            `WS_AUTH_OIDC_ISSUER` before forwarding to the editor, which binds
+            loopback-only on `WS_SERVER_PORT`. Requires `WS_AUTH_OIDC_ISSUER`,
+            `WS_AUTH_OIDC_CLIENT_ID` and `WS_AUTH_OIDC_CLIENT_SECRET`. Publish
+            the proxy port.
+
+          Any other value is treated as `password`.
+
+      oidc_allowed_emails:
+        type: string
+        default: null
+        delimiter: " "
+        since: 0.3.1
+        example: alice@corp.com bob@corp.com
+        description: Restrict OIDC login to an explicit email allowlist.
+        reference: /editor/authentication
+        longDescription: |
+          A **space-delimited** list. When unset, any email the IdP
+          authenticates is allowed. `oidc` assumes a single-user workspace
+          whose authorization is enforced upstream. Only used when
+          `WS_AUTH_MODE=oidc`.
+
+      oidc_allowed_groups:
+        type: string
+        default: null
+        delimiter: " "
+        since: 0.3.1
+        example: engineering platform
+        description: Restrict OIDC login to members of these IdP groups.
+        reference: /editor/authentication
+        longDescription: |
+          A **space-delimited** list mapped to oauth2-proxy `--allowed-group`.
+          Only used when `WS_AUTH_MODE=oidc`.
+
+      oidc_client_id:
+        type: string
+        default: null
+        since: 0.3.1
+        example: workspace
+        description: OIDC client ID. Required when `WS_AUTH_MODE=oidc`.
+        reference: /editor/authentication
+
+      oidc_client_secret:
+        type: string
+        default: null
+        secret: true
+        since: 0.3.1
+        description: OIDC client secret. Required when `WS_AUTH_MODE=oidc`.
+        reference: /editor/authentication
+        longDescription: |
+          Required for oidc mode. oauth2-proxy authenticates to the IdP as a
+          confidential client and refuses to start without it. PKCE
+          (`--code-challenge-method=S256`) is layered on top as defence in
+          depth. Register the workspace as a confidential client and supply its
+          secret here. Never baked or shared, provide it per deployment via the
+          resolution chain below.
+
+          **Resolution chain:**
+
+          1. Env literal: `WS_AUTH_OIDC_CLIENT_SECRET=...`.
+          2. `file:` env value: `WS_AUTH_OIDC_CLIENT_SECRET=file:/path/to/secret`.
+          3. Convention default: file mounted at
+             `/run/secrets/workspace/auth/oidc_client_secret`.
+          4. Schema default *(unset)*.
+
+      oidc_cookie_secret:
+        type: string
+        default: null
+        secret: true
+        since: 0.3.1
+        description: Secret that signs and encrypts the oauth2-proxy session cookie.
+        reference: /editor/authentication
+        longDescription: |
+          A 16, 24, or 32-byte secret (raw or base64). When unset it is
+          generated once and persisted under the workspace home so sessions
+          survive restarts and redeploys that reattach the volume. For
+          multi-replica or volume-less deployments, set this to a shared value
+          so every instance signs cookies identically. Only used when
+          `WS_AUTH_MODE=oidc`.
+
+          **Resolution chain:**
+
+          1. Env literal: `WS_AUTH_OIDC_COOKIE_SECRET=...`.
+          2. `file:` env value: `WS_AUTH_OIDC_COOKIE_SECRET=file:/path/to/secret`.
+          3. Convention default: file mounted at
+             `/run/secrets/workspace/auth/oidc_cookie_secret`.
+          4. Generated and persisted *(unset)*.
+
+      oidc_forbidden_message:
+        type: string
+        default: Contact your administrator to request access; retrying will not help.
+        since: 0.3.1
+        example: Contact the platform team to request access.
+        description: Custom guidance shown on the OIDC not-authorized (403) page.
+        reference: /editor/authentication
+        longDescription: |
+          Replaces the default guidance on the 403 error page shown when an
+          authenticated user is denied (failed group/email allowlist). When
+          unset, a default "contact your administrator" message is shown. Only
+          used when `WS_AUTH_MODE=oidc`.
+
+      oidc_issuer:
+        type: string
+        default: null
+        since: 0.3.1
+        example: https://idp.example.com
+        description: OIDC issuer URL. Required when `WS_AUTH_MODE=oidc`.
+        reference: /editor/authentication
+        longDescription: |
+          The OpenID Connect issuer (discovery base URL). For Active Directory,
+          point at an OIDC-fronting issuer (Entra ID, Keycloak, dex) rather than
+          raw LDAP.
+
+      oidc_redirect_url:
+        type: string
+        default: null
+        since: 0.3.1
+        example: https://ws.example.com/oauth2/callback
+        description: Explicit OAuth redirect URL override.
+        reference: /editor/authentication
+        longDescription: |
+          When unset, oauth2-proxy derives the callback from the incoming
+          request host as `https://<host>/oauth2/callback`. Set this when the
+          externally-visible host differs from what oauth2-proxy can infer
+          (e.g. behind a terminator that rewrites the Host header). The in-IDE
+          logout action also uses this value to build the sign-out URL. Only
+          used when `WS_AUTH_MODE=oidc`.
+
+      oidc_scopes:
+        type: string
+        default: openid email profile
+        delimiter: " "
+        since: 0.3.1
+        example: openid email profile groups
+        description: OAuth scopes requested at login.
+        reference: /editor/authentication
+        longDescription: |
+          A **space-delimited** scope list requested from the IdP. Add `groups`
+          when you use `WS_AUTH_OIDC_ALLOWED_GROUPS` and your IdP exposes a
+          `groups` scope. Only used when `WS_AUTH_MODE=oidc`.
+
       password:
         type: string
         default: null
@@ -298,16 +469,6 @@ envs:
           Accepts a **space-delimited** list of extensions.
         reference: /editor/extensions
 
-      additional_vs_extensions_dir:
-        type: string
-        default: null
-        deprecated: 0.2.0
-        reference: /editor/extensions
-        example: /additional-extensions
-        description: Installs `.vsix` file found in this directory.
-        longDescription: |
-          Use this when you package proprietary or pre-downloaded extensions.
-
       comments_disable_font:
         type: boolean
         default: false
@@ -374,6 +535,7 @@ envs:
         type: string
         default: null
         delimiter: ","
+        pattern: "[a-zA-Z0-9.:/_~?#=&%+-]+"
         since: 0.2.0
         example: >-
           https://github.com,https://stackoverflow.com
@@ -405,14 +567,28 @@ envs:
 
       dir:
         type: path
-        default: /usr/share/workspace/features
+        default: /usr/share/workspace/features.d
         reference: /editor/features
         since: 0.20.0
         description: Directory path where additional features are located.
         longDescription: |
           Specify the full path to the directory containing the features
           to be loaded or referenced at startup.
 
+      store_allow_fallback:
+        type: boolean
+        default: false
+        since: 0.3.0
+        reference: /editor/features#feature-store
+        description: Allow upstream Debian fallback on older-drift detection.
+        longDescription: |
+          When the ws-feature-store serves a package strictly older than what
+          the workspace already has installed, opt into temporarily re-enabling
+          `debian.sources` for this install. Only effective when
+          `WS_APT_DISABLE_REPOS` does NOT cover `debian`. In air-gapped
+          deployments (no path to `deb.debian.org`) this knob has no effect —
+          the install proceeds via the per-install Pin fragment regardless.
+
       store_url:
         type: string
         default: null
@@ -470,6 +646,12 @@ envs:
 
   logging:
     properties:
+      auth_proxy_file:
+        type: string
+        default: auth-proxy.log
+        description: Log file for the OIDC authentication proxy.
+        since: 0.3.1
+
       dir:
         type: path
         default: /var/log/workspace
@@ -486,12 +668,24 @@ envs:
           `"${WS_LOGGING_DIR}/${WS_LOGGING_MAIN_FILE}"`.
         since: 0.0.22
 
+      docker_file:
+        type: string
+        default: dockerd.log
+        description: Log file for the in-container Docker daemon.
+        since: 0.3.0
+
       main_file:
         type: string
         default: workspace.log
         description: Combined log file for `stdout` and `stderr`.
         since: 0.0.21
 
+      metrics_file:
+        type: string
+        default: metrics.log
+        description: Log file for the metrics exporter.
+        since: 0.3.0
+
   metrics:
     properties:
       collectors:
@@ -576,18 +770,20 @@ envs:
              `/run/secrets/workspace/secrets/master_key`.
           5. Schema default *(unset)*.
 
-      vault:
-        type: path
-        default: ~/.ws/vault/secrets.yaml
-        example: /custom/path/vault/secrets.yaml
-        since: 0.1.1
-        description: Path to the secrets vault manifest file.
-        longDescription: |
-          A YAML file containing encrypted secrets that can be decrypted and
-          deployed to various destinations during startup.
-
   server:
     properties:
+      auth_proxy_port:
+        type: integer
+        default: 38080
+        since: 0.3.1
+        description: Port the OIDC auth proxy listens on when WS_AUTH_MODE is oidc.
+        reference: /editor/authentication
+        longDescription: |
+          When WS_AUTH_MODE=oidc the auth proxy listens on this port and
+          forwards authenticated traffic to the editor on WS_SERVER_PORT.
+          Publish this port instead of WS_SERVER_PORT so every request is
+          authenticated before it reaches the editor.
+
       port:
         type: integer
         default: 8080
@@ -598,17 +794,21 @@ envs:
         type: string
         default: null
         delimiter: " "
+        pattern: "[a-zA-Z0-9.{}_-]+"
         since: 0.0.20
         example: ws.dev local.ws.dev
         description: >-
           Domain suffix used to expose server's forwarded ports.
         longDescription: >-
           Accepts either a single domain suffix or multiple
-          **space-delimited** suffixes.
+          **space-delimited** suffixes. Each suffix is exposed as
+          `{{port}}.<suffix>`; the `{{port}}.` prefix is added automatically
+          unless the suffix already contains a `{{port}}` placeholder
+          (e.g. `{{port}}-project.ws.dev`). Wildcards are not accepted.
           > Multiple domain support was added in `v0.0.22`.
         reference: /editor/port-forwarding
 
-      root_dir:
+      root:
         type: path
         default: /workspace
         since: 0.0.20
@@ -747,6 +947,7 @@ envs:
         type: string
         default: null
         delimiter: " "
+        pattern: "[a-zA-Z0-9_-]+"
         since: 0.0.20
         example: php
         description: Loads additional `oh-my-zsh` plugins.
@@ -817,6 +1018,7 @@ envs:
           golang helm kubectl npm python pip
           ssh-agent yarn zsh-autosuggestions
         delimiter: " "
+        pattern: "[a-zA-Z0-9_-]+"
         example: kubectl npm python pip
         description: Enables built-in `oh-my-zsh` plugins.
         longDescription: |
@@ -978,6 +1180,14 @@ deprecated:
       Set WS_SECRETS_MASTER_KEY=file:/path or mount the secret at
       /run/secrets/workspace/secrets/master_key.
 
+  WS_SECRETS_VAULT:
+    since: 0.3.0
+    removed: 0.3.0
+    message: |
+      Place your vault manifest at `~/.ws/vault/secrets.yaml`;
+      it is auto-discovered at boot. No environment variable
+      is required.
+
   WS_ZSH_EXTRA_PLUGINS:
     use: WS_ZSH_ADDITIONAL_PLUGINS
     since: 0.0.20