Skip to content

App Secret ​

Introduction ​

Every Windwalker application has one root secret, read from the APP_SECRET environment variable. The framework uses it as the input for keys that protect data, so one value in the environment controls every derived key. Keep it unique to each environment and out of the code.

This page covers the secret itself. For how environment files are loaded, see environment variables.

Minimal Setup ​

The framework generates APP_SECRET automatically when the application is first set up. You only need to generate a new value when you rotate the secret. Use the crypt:secret command with --replace to write the new value into .env without pasting it by hand:

bash
php windwalker crypt:secret --replace

The command prints a random value with the base64url: prefix. The prefix tells the framework how to decode it. Without --replace, add the printed output to your environment file:

dotenv
# .env.local
APP_SECRET=base64url:...

The application configuration reads the variable into app.secret:

php
// etc/conf/app.config.php
return [
    'secret' => env('APP_SECRET'),
];

INFO

crypt:secret --replace writes to .env by default, not .env.local. Use --output to write the value to a file of your choice.

If you run this command without --replace, the output is a plain random value, so you can also use it outside the application:

  • Copy it by hand into a secret or key setting of another system.
  • Change the encoding format with the command options when the target system expects a different format.
  • Omit the prefix when the consumer does not expect base64url:.

Run php windwalker crypt:secret --help to see the available options. Without --replace, the command works as a simple password or key generator.

A Complete Example ​

The following is a designed example, not a framework class. A service that signs download links asks SecretKeeperInterface for a key derived for that one purpose:

php
use Windwalker\Core\Application\SecretKeeperInterface;

class DownloadSigner
{
    public function __construct(
        protected SecretKeeperInterface $secrets,
    ) {}

    public function sign(string $path, int $expires): string
    {
        $key = $this->secrets->getSecret('download-link');

        return hash_hmac('sha256', "$path|$expires", $key);
    }
}

The service receives the keeper through its constructor, so the application container supplies it. The derived key differs from the root secret and from keys derived for other purposes.

getSecret() is also available on AppContext and ApplicationInterface. Inject SecretKeeperInterface when you do not want to depend on the whole application. The service then depends only on the secret.

A Complete Example ​

A service that signs download links should not use the master secret directly. It asks SecretKeeperInterface for a key that is derived for one purpose:

php
use Windwalker\Core\Application\SecretKeeperInterface;

class DownloadSigner
{
    public function __construct(
        protected SecretKeeperInterface $secrets,
    ) {}

    public function sign(string $path, int $expires): string
    {
        $key = $this->secrets->getSecret('download-link');

        return hash_hmac('sha256', "$path|$expires", $key);
    }
}

The derived key is different from the master secret and from the keys derived for other purposes. A leaked download link therefore does not reveal a key that is used for sessions or encryption.

Derived Keys ​

getSecret() takes an optional purpose name. With a name, it returns a 32-byte key derived with HKDF-SHA256. The name is the HKDF info string, and no salt is used. Use one name per purpose, kept in a constant so signing and verification use the same value (designed example):

php
final class KeyPurpose
{
    public const DOWNLOAD_LINK = 'download-link';
}

$key = $secrets->getSecret(KeyPurpose::DOWNLOAD_LINK);

Without a name, getSecret() returns the decoded root secret. Use that form only when a library needs the raw value.

TIP

Do not use the raw root secret directly, for any purpose. Derive a new key with a purpose name instead, so each use gets its own key.

The framework itself uses this pattern. TaskPayload signs task payloads with a key derived for the task.run purpose.

WARNING

A purpose name must match exactly. A changed or misspelled name derives a different key, so existing signatures stop verifying.

Empty Secret Behavior ​

If APP_SECRET is not set, env() returns null, and the keeper returns an empty string for the unnamed call. The named call fails:

  • getSecret() with no name returns '' and raises no error.
  • getSecret('name') throws a ValueError from hash_hkdf().
  • Task signing throws a LogicException ("An application secret is required") when the secret is empty.

WARNING

An unset secret does not stop unnamed calls. Check that APP_SECRET is set in every environment before you deploy.

Rotating the Secret ​

Changing APP_SECRET changes every key derived from it, so signatures and encrypted data made with the old value no longer verify. The source does not define a rotation procedure, so plan the migration yourself.

WARNING

Rotation invalidates data protected with the old secret. Re-encrypt stored data and reissue signed links before you retire the old value.

Storage and Safety ​

Keep a separate secret for each environment, and keep it out of the code.

WARNING

Never commit APP_SECRET to git. Do not print it in logs or error pages. Store it in .env.local or in the server environment.

Released under the MIT License.