🔄 Sync shared files from ws-meta

charts/workspace/scripts/env.reference.yaml

@@ -99,7 +99,7 @@ envs:
         type: string
         default: null
         delimiter: " "
-        since: 0.2.2
+        since: 0.3.0
         reference: /tools/apt
         example: x11 mail
         description: Disables specified APT install restrictions or all restrictions.
@@ -125,13 +125,14 @@ envs:
       disable_sudo:
         type: boolean
         default: false
-        since: 0.0.20
+        since: 0.3.0
         description: Disables password-less `sudo`.
 
       github_token:
         type: string
         default: null
-        since: 0.2.2
+        secret: true
+        since: 0.3.0
         example: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
         description: GitHub personal access token for the workspace and `gh`.
         reference: /editor/authentication
@@ -141,25 +142,18 @@ envs:
           Terminal `git` HTTPS auth is not wired — use SSH or a credential
           helper.
 
-          For vault entries, prefer `type: file` over `type: env`. The
-          latter writes to `~/.zshenv` and leaks the token to interactive
-          shells.
+          **Resolution chain:**
 
-      github_token_file:
-        type: string
-        default: /run/secrets/workspace/auth_github_token
-        since: 0.2.2
-        description: Path to a file containing the GitHub personal access token.
-        reference: /editor/authentication
-        longDescription: |
-          **GitHub token lookup precedence:**
-
-          1. `WS_AUTH_GITHUB_TOKEN_FILE` *(this variable)*.
-          2. `WS_AUTH_GITHUB_TOKEN` *(env var)*.
+          1. Env literal: `WS_AUTH_GITHUB_TOKEN=ghp_...`.
+          2. `file:` env value: `WS_AUTH_GITHUB_TOKEN=file:/path/to/token`.
+          3. Convention default: file mounted at
+             `/run/secrets/workspace/auth/github_token`.
+          4. Schema default *(unset)*.
 
       password:
         type: string
         default: null
+        secret: true
         since: 0.0.20
         example: super_duper_secret
         description: Plaintext password for web login.
@@ -168,23 +162,21 @@ envs:
           Use only in ephemeral or local environments, never in shared or
           production deployments.
 
-      password_file:
-        type: string
-        default: /run/secrets/workspace/auth_password
-        since: 0.2.0
-        description: Path to a file containing the plaintext password.
-        reference: /editor/authentication
-        longDescription: |
-          **Password lookup precedence:**
+          **Resolution chain:**
 
-          1. `WS_AUTH_PASSWORD_HASHED_FILE` *(hashed file)*.
-          2. `WS_AUTH_PASSWORD_HASHED` *(hashed env var)*.
-          3. `WS_AUTH_PASSWORD_FILE` *(this variable)*.
-          4. `WS_AUTH_PASSWORD` *(plaintext env var)*.
+          1. Env literal: `WS_AUTH_PASSWORD=mySecret`.
+          2. `file:` env value: `WS_AUTH_PASSWORD=file:/path/to/password`.
+          3. Convention default: file mounted at
+             `/run/secrets/workspace/auth/password`.
+          4. Schema default *(unset)*.
+
+          `WS_AUTH_PASSWORD_HASHED` takes precedence over this when both
+          resolve to a non-empty value.
 
       password_hashed:
         type: string
         default: null
+        secret: true
         since: 0.0.20
         example: >-
           $argon2i$v=19$m=4096,t=3,p=1$...$...
@@ -193,19 +185,13 @@ envs:
         longDescription: |
           Takes precedence over plaintext password when both are set.
 
-      password_hashed_file:
-        type: string
-        default: /run/secrets/workspace/auth_password_hashed
-        since: 0.2.0
-        description: Path to a file containing the Argon2 hashed password.
-        reference: /editor/authentication
-        longDescription: |
-          **Password lookup precedence:**
+          **Resolution chain:**
 
-          1. `WS_AUTH_PASSWORD_HASHED_FILE` *(this variable)*.
-          2. `WS_AUTH_PASSWORD_HASHED` *(hashed env var)*.
-          3. `WS_AUTH_PASSWORD_FILE` *(plaintext file)*.
-          4. `WS_AUTH_PASSWORD` *(plaintext env var)*.
+          1. Env literal: `WS_AUTH_PASSWORD_HASHED=<argon2-hash>`.
+          2. `file:` env value: `WS_AUTH_PASSWORD_HASHED=file:/path/to/hash`.
+          3. Convention default: file mounted at
+             `/run/secrets/workspace/auth/password_hashed`.
+          4. Schema default *(unset)*.
 
   ca:
     name: Enterprise CA
@@ -277,7 +263,7 @@ envs:
         description: Hides the model name in the Claude statusline.
 
       statusline_script:
-        type: string
+        type: path
         default: /etc/claude-code/statusline.zsh
         since: 0.2.0
         reference: /tools/claude
@@ -352,7 +338,7 @@ envs:
           {"editor.fontSize": 16, "[python]": {"editor.tabSize": 4}}
 
       settings_merge_file:
-        type: string
+        type: path
         default: null
         since: 0.1.2
         reference: /editor/settings
@@ -375,7 +361,7 @@ envs:
           {"editor.fontSize": 16}
 
       settings_override_file:
-        type: string
+        type: path
         default: null
         since: 0.1.2
         reference: /editor/settings
@@ -418,7 +404,7 @@ envs:
           Accepts a **space-delimited** list of features.
 
       dir:
-        type: string
+        type: path
         default: /usr/share/workspace/features
         reference: /editor/features
         since: 0.20.0
@@ -485,7 +471,7 @@ envs:
   logging:
     properties:
       dir:
-        type: string
+        type: path
         default: /var/log/workspace
         description: Base directory for all workspace logs.
         since: 0.0.21
@@ -570,6 +556,7 @@ envs:
       master_key:
         type: string
         default: null
+        secret: true
         example: dGhpcyBpcyBhIHNlY3JldCBrZXkgZXhhbXBsZQ==
         since: 0.1.1
         description: Master encryption key for secrets vault.
@@ -580,35 +567,17 @@ envs:
           - A base64-encoded string.
           - A plaintext string.
 
-          **Master key lookup precedence:**
-
-          1. CLI `--master` flag *(if provided)*.
-          2. `WS_SECRETS_MASTER_KEY` *(this variable)*.
-          3. `WS_SECRETS_MASTER_KEY_FILE`.
-          4. `/etc/workspace/master.key` *(default path)*.
-
-      master_key_file:
-        type: string
-        default: /etc/workspace/master.key
-        example: /etc/workspace/custom-master.key
-        since: 0.1.1
-        description: Path to file containing the master encryption key.
-        longDescription: |
-          Used to encrypt and decrypt secrets in the vault.
-          Can be provided as:
-
-          - A base64-encoded string.
-          - A plaintext string.
-
-          **Master key lookup precedence:**
+          **Resolution chain:**
 
           1. CLI `--master` flag *(if provided)*.
-          2. `WS_SECRETS_MASTER_KEY`.
-          3. `WS_SECRETS_MASTER_KEY_FILE` *(this variable)*.
-          4. `/etc/workspace/master.key` *(default path)*.
+          2. Env literal: `WS_SECRETS_MASTER_KEY=<key>`.
+          3. `file:` env value: `WS_SECRETS_MASTER_KEY=file:/path/to/key`.
+          4. Convention default: file mounted at
+             `/run/secrets/workspace/secrets/master_key`.
+          5. Schema default *(unset)*.
 
       vault:
-        type: string
+        type: path
         default: ~/.ws/vault/secrets.yaml
         example: /custom/path/vault/secrets.yaml
         since: 0.1.1
@@ -640,25 +609,34 @@ envs:
         reference: /editor/port-forwarding
 
       root_dir:
-        type: string
+        type: path
         default: /workspace
         since: 0.0.20
         description: Root directory for the workspace.
         longDescription: |
           **This should only be overridden in extreme cases.**
 
       ssl_cert:
-        type: string
+        type: path
         default: null
+        secret: true
         reference: /settings/https
         example: /etc/workspace/ssl/server.crt
         since: 0.0.21
-        description: Path or inline PEM for the server certificate.
+        description: Inline PEM or `file:` path for the server certificate.
         longDescription: |
           Accepts either:
-          - A full path to the mounted PEM-encoded certificate
           - Literal certificate body starting with `-----BEGIN CERTIFICATE-----`
               *(newline characters may be provided as `\n` escapes)*.
+          - A `file:` env value: `WS_SERVER_SSL_CERT=file:/path/to/server.crt`.
+
+          **Resolution chain:**
+
+          1. Env literal *(inline PEM)*.
+          2. `file:` env value *(reads the file at the given path)*.
+          3. Convention default: file mounted at
+             `/run/secrets/workspace/server/ssl_cert`.
+          4. Schema default *(unset)*.
 
           When this is unset but `WS_SERVER_SSL_KEY` is provided, the
           key is reused to mint a self-signed certificate for
@@ -673,12 +651,39 @@ envs:
         description: Space-delimited DNS names for self-signed certificate.
 
       ssl_key:
-        type: string
+        type: path
         default: null
+        secret: true
         reference: /settings/https
         since: 0.0.21
         example: /etc/workspace/ssl/server.key
-        description: Path or inline PEM for the private key.
+        description: Inline PEM or `file:` path for the private key.
+        longDescription: |
+          Accepts either:
+          - Literal key body starting with `-----BEGIN PRIVATE KEY-----`
+              *(newline characters may be provided as `\n` escapes)*.
+          - A `file:` env value: `WS_SERVER_SSL_KEY=file:/path/to/server.key`.
+
+          **Resolution chain:**
+
+          1. Env literal *(inline PEM)*.
+          2. `file:` env value *(reads the file at the given path)*.
+          3. Convention default: file mounted at
+             `/run/secrets/workspace/server/ssl_key`.
+          4. Schema default *(unset)*.
+
+      ssl_root:
+        type: path
+        default: /etc/workspace/ssl
+        reference: /settings/https
+        since: 0.3.0
+        description: Root directory for self-signed SSL artifacts.
+        longDescription: |
+          Directory where startup writes the generated self-signed certificate
+          and private key when `WS_SERVER_SSL_KEY` is supplied without
+          `WS_SERVER_SSL_CERT`.
+
+          **This is a structural path; overrides are discouraged.**
 
   startup:
     properties:
@@ -826,6 +831,30 @@ deprecated:
     since: 0.0.20
     removed: 0.1.0
 
+  WS_AUTH_GITHUB_TOKEN_FILE:
+    use: WS_AUTH_GITHUB_TOKEN
+    since: 0.3.0
+    removed: 0.3.0
+    message: |
+      Set WS_AUTH_GITHUB_TOKEN=file:/path or mount the secret at
+      /run/secrets/workspace/auth/github_token.
+
+  WS_AUTH_PASSWORD_FILE:
+    use: WS_AUTH_PASSWORD
+    since: 0.3.0
+    removed: 0.3.0
+    message: |
+      Set WS_AUTH_PASSWORD=file:/path or mount the secret at
+      /run/secrets/workspace/auth/password.
+
+  WS_AUTH_PASSWORD_HASHED_FILE:
+    use: WS_AUTH_PASSWORD_HASHED
+    since: 0.3.0
+    removed: 0.3.0
+    message: |
+      Set WS_AUTH_PASSWORD_HASHED=file:/path or mount the secret at
+      /run/secrets/workspace/auth/password_hashed.
+
   WS_CA_ADDITIONAL_CERT_ALLOW_INSECURE:
     use: WS_CA_ADDITIONAL_CERT_INSECURE_ENDPOINTS
     since: 0.0.22
@@ -941,6 +970,14 @@ deprecated:
     since: 0.0.20
     removed: 0.1.0
 
+  WS_SECRETS_MASTER_KEY_FILE:
+    use: WS_SECRETS_MASTER_KEY
+    since: 0.3.0
+    removed: 0.3.0
+    message: |
+      Set WS_SECRETS_MASTER_KEY=file:/path or mount the secret at
+      /run/secrets/workspace/secrets/master_key.
+
   WS_ZSH_EXTRA_PLUGINS:
     use: WS_ZSH_ADDITIONAL_PLUGINS
     since: 0.0.20