Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(conversations): add signing secret rotation grace window (#120602)

Patriciof623c569535f
diff --git a/frontend/src/scenes/team-activity/teamActivityDescriber.tsx b/frontend/src/scenes/team-activity/teamActivityDescriber.tsx
index 346fda7f0923..bbc274b8497b 100644
--- a/frontend/src/scenes/team-activity/teamActivityDescriber.tsx
+++ b/frontend/src/scenes/team-activity/teamActivityDescriber.tsx
@@ -168,7 +168,11 @@ function createExperimentsDefaultHandler(fieldName: string, format: (value: unkn
}
const TEAM_PROPERTIES_MAPPING: Record<
- keyof TeamType | keyof ExperimentsConfig | 'heatmaps_screenshot_allowed_hostnames' | 'conversations_signing_secret',
+ | keyof TeamType
+ | keyof ExperimentsConfig
+ | 'heatmaps_screenshot_allowed_hostnames'
+ | 'conversations_signing_secret'
+ | 'conversations_signing_secret_previous',
(change: ActivityChange) => ChangeMapping | null
> = {
// API-related tokens
@@ -179,6 +183,14 @@ const TEAM_PROPERTIES_MAPPING: Record<
'generated',
'rotated'
),
+ conversations_signing_secret_previous: (change) => {
+ if (change.action !== 'deleted') {
+ return null
+ }
+ return {
+ description: [<>Expired the previous Conversations identity verification secret</>],
+ }
+ },
heatmaps_screenshot_secret: createApiTokenHandler('heatmap screenshot value', 'generated', 'rotated'),
heatmaps_screenshot_allowed_hostnames: createArrayChangeHandler('approved screenshot hostnames'),
secret_api_token_backup: (change) => {
diff --git a/posthog/models/signals.py b/posthog/models/signals.py
index d6641ea437ba..77a75f035343 100644
--- a/posthog/models/signals.py
+++ b/posthog/models/signals.py
@@ -19,6 +19,11 @@ model_activity_signal = Signal()
# receiver rolls the rotation back. Work outside the database belongs in on_commit.
secret_api_token_rotated = Signal()
+# Sent by Team.delete_secret_token_backup_and_save inside the deletion's transaction,
+# with `deleted_token`. Deleting the backup is an explicit revocation, so dependent
+# stores must drop any copy of that credential (e.g. the signing secret's grace copy).
+secret_api_token_backup_deleted = Signal()
+
def mutable_receiver(*args, **kwargs):
"""
diff --git a/posthog/models/team/team.py b/posthog/models/team/team.py
index 188128054c6d..d0265d0d1bd4 100644
--- a/posthog/models/team/team.py
+++ b/posthog/models/team/team.py
@@ -29,7 +29,7 @@ from posthog.models.project_secret_api_key import (
create_project_secret_api_key_for_token,
delete_project_secret_api_keys_for_token,
)
-from posthog.models.signals import mutable_receiver, secret_api_token_rotated
+from posthog.models.signals import mutable_receiver, secret_api_token_backup_deleted, secret_api_token_rotated
from posthog.models.utils import (
UUIDTClassicModel,
generate_random_token_heatmap_screenshot,
@@ -1000,7 +1000,9 @@ class Team(UUIDTClassicModel):
delete_project_secret_api_keys_for_token(self.id, expired_token)
# With the legacy verifiers off, only the mirror row authenticates the new token.
create_project_secret_api_key_for_token(self.id, new_token)
- secret_api_token_rotated.send(sender=self.__class__, team=self)
+ # expired_token lets receivers drop their own copies of the credential
+ # this rotation retires for good (it leaves the backup column too).
+ secret_api_token_rotated.send(sender=self.__class__, team=self, expired_token=expired_token)
except Exception:
# save() already cached this team (post_save) with the new tokens, which the
# rollback discarded. Rewrite that entry from the committed row.
@@ -1145,6 +1147,7 @@ class Team(UUIDTClassicModel):
self.secret_api_token_backup = None
self.save()
delete_project_secret_api_keys_for_token(self.id, old_backup_token)
+ secret_api_token_backup_deleted.send(sender=self.__class__, team=self, deleted_token=old_backup_token)
except Exception:
# save() already cached this team (post_save) with the cleared backup, which
# the rollback discarded. Rewrite that entry from the committed row.
diff --git a/products/conversations/backend/api/signing_secret.py b/products/conversations/backend/api/signing_secret.py
index 1f3083ea5271..21a9771b2f30 100644
--- a/products/conversations/backend/api/signing_secret.py
+++ b/products/conversations/backend/api/signing_secret.py
@@ -3,6 +3,7 @@ from __future__ import annotations
from typing import Any, cast
from django.db import transaction
+from django.utils import timezone
from drf_spectacular.utils import extend_schema
from rest_framework import serializers, viewsets
@@ -17,6 +18,7 @@ from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.auth import SessionAuthentication
from posthog.helpers.impersonation import is_impersonated
from posthog.models.activity_logging.activity_log import Change, Detail, log_activity
+from posthog.models.team import Team
from posthog.models.user import User
from posthog.models.utils import generate_random_token, mask_key_value
from posthog.permissions import TeamMemberStrictManagementPermission, TimeSensitiveActionPermission
@@ -35,6 +37,19 @@ class SigningSecretSerializer(serializers.Serializer):
allow_null=True,
help_text="When the secret last changed, or null when no secret exists yet.",
)
+ previous_secret_valid_until = serializers.DateTimeField(
+ read_only=True,
+ allow_null=True,
+ help_text="Until when the previous secret keeps verifying after a rotation, or null when no grace window is active.",
+ )
+
+
+def _serializer_payload(row: SigningSecret | None) -> dict[str, Any]:
+ return {
+ "secret": row.secret if row else None,
+ "updated_at": row.updated_at if row else None,
+ "previous_secret_valid_until": row.previous_secret_valid_until if row and row.previous_secret_active else None,
+ }
class _SessionOnlyPermission(BasePermission):
@@ -67,25 +82,48 @@ class SigningSecretViewSet(TeamAndOrgViewSetMixin, viewsets.GenericViewSet):
)
def list(self, request: Request, *args: Any, **kwargs: Any) -> Response:
row = SigningSecret.objects.for_team(self.team_id).first()
- serializer = SigningSecretSerializer(
- {"secret": row.secret if row else None, "updated_at": row.updated_at if row else None}
- )
+ serializer = SigningSecretSerializer(_serializer_payload(row))
return Response(serializer.data)
@extend_schema(
request=None,
responses=SigningSecretSerializer,
- description="Generate a new signing secret. Identity hashes signed with the previous secret stop verifying immediately.",
+ description="Generate a new signing secret. The previous secret keeps verifying identity hashes for 48 hours, then expires.",
)
@action(methods=["POST"], detail=False)
def rotate(self, request: Request, *args: Any, **kwargs: Any) -> Response:
- old_row = SigningSecret.objects.for_team(self.team_id).first()
# One transaction: a credential change without its audit row must not commit.
with transaction.atomic():
- row, _ = SigningSecret.objects.for_team(self.team_id).update_or_create(
- team_id=self.team_id,
- defaults={"secret": generate_random_token(), "rotated_independently": True},
+ # Locked get_or_create: two concurrent requests must serialize, or the loser
+ # overwrites the winner's secret right after it was shown to the winner.
+ # The loser then sees the winner's row and treats it as a rotation, so the
+ # winner's secret survives through the grace window.
+ row, created = (
+ SigningSecret.objects.for_team(self.team_id)
+ .select_for_update()
+ .get_or_create(
+ team_id=self.team_id,
+ defaults={"secret": generate_random_token(), "rotated_independently": True},
+ )
)
+ old_secret = None if created else row.secret
+ if not created:
+ # Grace only for a secret that was a trusted verification candidate.
+ # A stale mirror holds a retired key the staleness guard excluded;
+ # granting it grace would resurrect a revoked credential.
+ has_legacy = bool(self.team.secret_api_token or self.team.secret_api_token_backup)
+ old_secret_trusted = (
+ row.rotated_independently or not has_legacy or row.secret == self.team.secret_api_token
+ )
+ if old_secret_trusted:
+ row.previous_secret = row.secret
+ row.previous_secret_rotated_at = timezone.now()
+ else:
+ row.previous_secret = None
+ row.previous_secret_rotated_at = None
+ row.secret = generate_random_token()
+ row.rotated_independently = True
+ row.save()
log_activity(
organization_id=self.team.organization_id,
team_id=self.team_id,
@@ -99,13 +137,61 @@ class SigningSecretViewSet(TeamAndOrgViewSetMixin, viewsets.GenericViewSet):
changes=[
Change(
type="Team",
- action="created" if old_row is None else "changed",
+ action="created" if created else "changed",
field="conversations_signing_secret",
- before=mask_key_value(old_row.secret) if old_row else None,
+ before=mask_key_value(old_secret) if old_secret else None,
after=mask_key_value(row.secret),
)
],
),
)
- serializer = SigningSecretSerializer({"secret": row.secret, "updated_at": row.updated_at})
+ serializer = SigningSecretSerializer(_serializer_payload(row))
+ return Response(serializer.data)
+
+ @extend_schema(
+ request=None,
+ responses=SigningSecretSerializer,
+ description="End the rotation grace window now: the previous secret stops verifying immediately. Use it when the replaced secret may be compromised, or once every server runs the new one.",
+ )
+ @action(methods=["POST"], detail=False)
+ def expire_previous(self, request: Request, *args: Any, **kwargs: Any) -> Response:
+ with transaction.atomic():
+ # Team lock first: a legacy rotation racing this expiry would rewrite the
+ # backup column between the comparison below and the deletion.
+ locked_team = Team.objects.select_for_update(no_key=True).get(pk=self.team_id)
+ row = SigningSecret.objects.for_team(self.team_id).select_for_update().first()
+ if row and row.previous_secret:
+ expired = row.previous_secret
+ row.previous_secret = None
+ row.previous_secret_rotated_at = None
+ row.save(update_fields=["previous_secret", "previous_secret_rotated_at"])
+ # A legacy rotation leaves the same credential in the backup column,
+ # where it keeps verifying (and authenticating) while the legacy
+ # verifiers are on. Expiry is a revocation, so it must cover that copy.
+ if locked_team.secret_api_token_backup == expired:
+ locked_team.delete_secret_token_backup_and_save(
+ user=cast(User, request.user), is_impersonated_session=is_impersonated(request)
+ )
+ log_activity(
+ organization_id=self.team.organization_id,
+ team_id=self.team_id,
+ user=cast(User, request.user),
+ was_impersonated=is_impersonated(request),
+ scope="Team",
+ item_id=self.team_id,
+ activity="updated",
+ detail=Detail(
+ name=str(self.team.name),
+ changes=[
+ Change(
+ type="Team",
+ action="deleted",
+ field="conversations_signing_secret_previous",
+ before=mask_key_value(expired),
+ after=None,
+ )
+ ],
+ ),
+ )
+ serializer = SigningSecretSerializer(_serializer_payload(row))
return Response(serializer.data)
diff --git a/products/conversations/backend/api/tests/test_signing_secret_api.py b/products/conversations/backend/api/tests/test_signing_secret_api.py
index 92cb68bd6bc6..5f31ea4e2fe6 100644
--- a/products/conversations/backend/api/tests/test_signing_secret_api.py
+++ b/products/conversations/backend/api/tests/test_signing_secret_api.py
@@ -4,6 +4,7 @@ from datetime import timedelta
from posthog.test.base import APIBaseTest
from django.conf import settings as django_settings
+from django.utils import timezone
from parameterized import parameterized
from rest_framework import status
@@ -32,7 +33,7 @@ class TestSigningSecretAPI(APIBaseTest):
def test_get_without_a_row_returns_null(self):
response = self.client.get(self._url())
assert response.status_code == status.HTTP_200_OK
- assert response.json() == {"secret": None, "updated_at": None}
+ assert response.json() == {"secret": None, "updated_at": None, "previous_secret_valid_until": None}
def test_rotate_mints_an_independent_secret_and_leaves_the_legacy_token_alone(self):
self._make_admin()
@@ -47,6 +48,9 @@ class TestSigningSecretAPI(APIBaseTest):
assert response.json()["secret"] == row.secret
assert row.secret != "phs_legacy_token"
assert row.rotated_independently is True
+ assert row.previous_secret == "phs_legacy_token"
+ assert row.previous_secret_rotated_at is not None
+ assert response.json()["previous_secret_valid_until"] is not None
self.team.refresh_from_db()
assert self.team.secret_api_token == "phs_legacy_token"
@@ -61,6 +65,71 @@ class TestSigningSecretAPI(APIBaseTest):
assert change["action"] == "changed"
assert change["before"] is not None
+ def test_rotate_from_stale_row_grants_no_grace(self):
+ # A stale mirror holds a retired key the staleness guard excluded; grace for it
+ # would resurrect a revoked credential.
+ self._make_admin()
+ self.team.secret_api_token = "phs_legacy_token"
+ self.team.save()
+ SigningSecret.objects.for_team(self.team.id).create(team=self.team, secret="a_retired_secret")
+
+ response = self.client.post(self._url("rotate/"))
+
+ assert response.status_code == status.HTTP_200_OK
+ assert response.json()["previous_secret_valid_until"] is None
+ row = SigningSecret.objects.for_team(self.team.id).get()
+ assert row.previous_secret is None
+
+ def test_expire_previous_ends_the_grace_window(self):
+ self._make_admin()
+ SigningSecret.objects.for_team(self.team.id).create(
+ team=self.team,
+ secret="phs_new_secret",
+ rotated_independently=True,
+ previous_secret="phs_old_secret",
+ previous_secret_rotated_at=timezone.now(),
+ )
+
+ response = self.client.post(self._url("expire_previous/"))
+
+ assert response.status_code == status.HTTP_200_OK
+ assert response.json()["previous_secret_valid_until"] is None
+ row = SigningSecret.objects.for_team(self.team.id).get()
+ assert row.previous_secret is None
+ log = ActivityLog.objects.get(
+ scope="Team", team_id=self.team.id, detail__changes__0__field="conversations_signing_secret_previous"
+ )
+ assert "phs_old_secret" not in str(log.detail)
+
+ @parameterized.expand(
+ [
+ # Expiry is a revocation: the same credential sitting in the legacy backup
+ # column must die with it, or "Expire now" reports success while the key
+ # keeps verifying through the legacy fallback.
+ ("backup_holds_the_expired_secret", "phs_legacy_token", None),
+ ("unrelated_backup_is_kept", "phs_some_other_backup", "phs_some_other_backup"),
+ ]
+ )
+ def test_expire_previous_revokes_the_matching_legacy_backup(self, _name, backup, expected_backup_after):
+ self._make_admin()
+ self.team.secret_api_token = "phs_current_token"
+ self.team.secret_api_token_backup = backup
+ self.team.save()
+ SigningSecret.objects.for_team(self.team.id).create(
+ team=self.team,
+ secret="phs_current_token",
+ previous_secret="phs_legacy_token",
+ previous_secret_rotated_at=timezone.now(),
+ )
+
+ response = self.client.post(self._url("expire_previous/"))
+
+ assert response.status_code == status.HTTP_200_OK
+ self.team.refresh_from_db()
+ assert self.team.secret_api_token_backup == expected_backup_after
+ row = SigningSecret.objects.for_team(self.team.id).get()
+ assert row.previous_secret is None
+
def test_rotate_requires_admin(self):
response = self.client.post(self._url("rotate/"))
assert response.status_code == status.HTTP_403_FORBIDDEN
diff --git a/products/conversations/backend/api/tests/test_widget.py b/products/conversations/backend/api/tests/test_widget.py
index f9e3bf1a8e54..ad0d9ce6c3b5 100644
--- a/products/conversations/backend/api/tests/test_widget.py
+++ b/products/conversations/backend/api/tests/test_widget.py
@@ -1,5 +1,6 @@
import time
import uuid
+from datetime import timedelta
import time_machine
from posthog.test.base import BaseTest
@@ -903,6 +904,43 @@ class TestWidgetIdentityVerification(BaseTest):
self.assertEqual(response.json()["count"], 1)
self.assertEqual(_stale_counter() - before_stale, 0.0)
+ @parameterized.expand(
+ [
+ # A hash signed with the replaced secret keeps verifying inside the grace
+ # window and expires on its own after it, with no manual backup deletion.
+ ("inside_grace_window", timedelta(hours=47), status.HTTP_200_OK, "verified", "signing_secret_previous"),
+ ("after_grace_window", timedelta(hours=49), status.HTTP_403_FORBIDDEN, "invalid_hash", "none"),
+ ]
+ )
+ @override_settings(ACCEPT_TEAM_SECRET_TOKENS=False)
+ def test_list_tickets_previous_secret_grace_window(
+ self, _name: str, age: timedelta, expected_status: int, outcome: str, source: str
+ ) -> None:
+ replaced_secret = "a_replaced_secret"
+ SigningSecret.objects.for_team(self.team.id).create(
+ team=self.team,
+ secret="the_new_secret",
+ rotated_independently=True,
+ previous_secret=replaced_secret,
+ previous_secret_rotated_at=timezone.now() - age,
+ )
+ self._create_ticket()
+ before_stale = _stale_counter()
+ before_outcome = _verification_counter(outcome, source)
+
+ response = self.client.get(
+ "/api/conversations/v1/widget/tickets",
+ {
+ "identity_distinct_id": self.distinct_id,
+ "identity_hash": compute_identity_hash(self.distinct_id, replaced_secret),
+ },
+ **self._get_headers(),
+ )
+
+ self.assertEqual(response.status_code, expected_status)
+ self.assertEqual(_stale_counter() - before_stale, 0.0)
+ self.assertEqual(_verification_counter(outcome, source) - before_outcome, 1.0)
+
def test_list_tickets_legacy_hash_rejected_after_independent_rotation(self):
# Even with the kill switch on, an independent rotation must revoke the legacy
# token for verification, or old hashes stay valid forever.
diff --git a/products/conversations/backend/api/widget.py b/products/conversations/backend/api/widget.py
index 85d53a694f81..54e652b82d4f 100644
--- a/products/conversations/backend/api/widget.py
+++ b/products/conversations/backend/api/widget.py
@@ -72,7 +72,7 @@ TicketOwnershipMatch = Literal["distinct_id", "email"]
@frozen
class _IdentitySecret:
- source: Literal["signing_secret", "legacy_token", "legacy_backup"]
+ source: Literal["signing_secret", "signing_secret_previous", "legacy_token", "legacy_backup"]
secret: str = dataclass_field(repr=False)
@@ -109,7 +109,8 @@ def _identity_secrets(team: Team) -> list[_IdentitySecret]:
The conversations signing secret is where this credential is moving; the legacy
Team.secret_api_token stays a fallback so teams that predate the backfill keep
verifying. The rotation backup is accepted too, so hashes signed with the previous
- secret survive a rotation.
+ secret survive a rotation. A signing-secret rotation likewise keeps the replaced
+ value verifying for SigningSecret.PREVIOUS_SECRET_GRACE, then it expires on its own.
While the legacy column exists it remains the revocation authority: rotating and then
deleting the backup has to actually revoke the old key. The row is compared against the
@@ -131,6 +132,10 @@ def _identity_secrets(team: Team) -> list[_IdentitySecret]:
if signing_secret and signing_secret.secret:
if signing_secret.rotated_independently or not legacy_secrets or signing_secret.secret == team.secret_api_token:
secrets.append(_IdentitySecret(source="signing_secret", secret=signing_secret.secret))
+ # Rotation grace: hashes signed with the replaced secret keep verifying until
+ # the window closes. Tied to the trusted branch so a stale row contributes nothing.
+ if signing_secret.previous_secret_active and signing_secret.previous_secret:
+ secrets.append(_IdentitySecret(source="signing_secret_previous", secret=signing_secret.previous_secret))
else:
SIGNING_SECRET_STALE_COUNTER.inc()
logger.warning("Conversations signing secret is stale, skipping it", extra={"team_id": team.id})
diff --git a/products/conversations/backend/migrations/0078_signingsecret_previous_secret_and_more.py b/products/conversations/backend/migrations/0078_signingsecret_previous_secret_and_more.py
new file mode 100644
index 000000000000..6cad43c24f5f
--- /dev/null
+++ b/products/conversations/backend/migrations/0078_signingsecret_previous_secret_and_more.py
@@ -0,0 +1,24 @@
+# Generated by Django 5.2.18 on 2026-10-20 18:22
+
+from django.db import migrations, models
+
+import posthog.helpers.encrypted_fields
+
+
+class Migration(migrations.Migration):
+ dependencies = [
+ ("conversations", "0077_signingsecret_rotated_independently"),
+ ]
+
+ operations = [
+ migrations.AddField(
+ model_name="signingsecret",
+ name="previous_secret",
+ field=posthog.helpers.encrypted_fields.EncryptedTextField(null=True),
+ ),
+ migrations.AddField(
+ model_name="signingsecret",
+ name="previous_secret_rotated_at",
+ field=models.DateTimeField(null=True),
+ ),
+ ]
diff --git a/products/conversations/backend/migrations/max_migration.txt b/products/conversations/backend/migrations/max_migration.txt
index 23c079ed6c10..a793ff27fd59 100644
--- a/products/conversations/backend/migrations/max_migration.txt
+++ b/products/conversations/backend/migrations/max_migration.txt
@@ -1 +1 @@
-0077_signingsecret_rotated_independently
+0078_signingsecret_previous_secret_and_more
diff --git a/products/conversations/backend/models/signing_secret.py b/products/conversations/backend/models/signing_secret.py
index 725baba2ed42..0a4c9d46e001 100644
--- a/products/conversations/backend/models/signing_secret.py
+++ b/products/conversations/backend/models/signing_secret.py
@@ -1,6 +1,9 @@
from __future__ import annotations
+from datetime import datetime, timedelta
+
from django.db import models
+from django.utils import timezone
from posthog.helpers.encrypted_fields import EncryptedTextField
from posthog.models.scoping.manager import EnvironmentScopedManager
@@ -21,6 +24,10 @@ class SigningSecret(UUIDModel):
readers pass the environment's own id via `objects.for_team(team.id)`.
"""
+ # How long the previous secret keeps verifying after a rotation. Customers sign
+ # hashes on their servers, so they need a deploy window to pick up the new value.
+ PREVIOUS_SECRET_GRACE = timedelta(hours=48)
+
objects = EnvironmentScopedManager()
# db_constraint=False so CreateModel takes no lock on posthog_team.
@@ -35,6 +42,12 @@ class SigningSecret(UUIDModel):
secret = EncryptedTextField()
# Set on rotation via the conversations endpoint: the secret stops mirroring the legacy token.
rotated_independently = models.BooleanField(default=False)
+ # The secret that `secret` replaced, kept verifying for PREVIOUS_SECRET_GRACE after
+ # previous_secret_rotated_at so in-flight hashes survive a rotation. Expiry is judged
+ # at read time; the next rotation supersedes the value, and the revocation paths
+ # (expire_previous, the rotation and backup-deletion receivers) clear it.
+ previous_secret = EncryptedTextField(null=True)
+ previous_secret_rotated_at = models.DateTimeField(null=True)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
@@ -43,3 +56,14 @@ class SigningSecret(UUIDModel):
def __str__(self) -> str:
return f"SigningSecret(team={self.team_id})"
+
+ @property
+ def previous_secret_valid_until(self) -> datetime | None:
+ if not self.previous_secret or not self.previous_secret_rotated_at:
+ return None
+ return self.previous_secret_rotated_at + self.PREVIOUS_SECRET_GRACE
+
+ @property
+ def previous_secret_active(self) -> bool:
+ valid_until = self.previous_secret_valid_until
+ return valid_until is not None and timezone.now() < valid_until
diff --git a/products/conversations/backend/signals.py b/products/conversations/backend/signals.py
index 2f51677b4108..15261b21c7ab 100644
--- a/products/conversations/backend/signals.py
+++ b/products/conversations/backend/signals.py
@@ -14,7 +14,7 @@ from posthog.exceptions_capture import capture_exception
from posthog.models import User
from posthog.models.comment import Comment
from posthog.models.instance_setting import get_instance_setting
-from posthog.models.signals import secret_api_token_rotated
+from posthog.models.signals import secret_api_token_backup_deleted, secret_api_token_rotated
from .ai.human_outcome import maybe_record_human_outcome
from .cache import invalidate_identity_tickets_cache, invalidate_messages_cache, invalidate_tickets_cache
@@ -617,7 +617,35 @@ def sync_signing_secret_on_rotation(sender, team, **kwargs):
.select_for_update()
.get_or_create(team=team, defaults={"secret": team.secret_api_token})
)
- if created or row.rotated_independently:
+ if created:
return
+ # A second legacy rotation retires the old backup for good (expired_token). An
+ # independent row may still hold that credential as its grace copy from the
+ # rotation that decoupled it; a revoked key must not keep verifying through it.
+ expired_token = kwargs.get("expired_token")
+ if expired_token and row.previous_secret == expired_token:
+ row.previous_secret = None
+ row.previous_secret_rotated_at = None
+ row.save(update_fields=["previous_secret", "previous_secret_rotated_at"])
+ if row.rotated_independently:
+ return
+ # No grace here: for a legacy rotation the backup column is the grace mechanism
+ # (the old key keeps working until the backup is deleted or expires on the next
+ # rotation). A previous_secret copy would outlive or duplicate those semantics,
+ # so a mirroring row never carries one.
+ row.previous_secret = None
+ row.previous_secret_rotated_at = None
row.secret = team.secret_api_token
- row.save(update_fields=["secret"])
+ row.save(update_fields=["secret", "previous_secret", "previous_secret_rotated_at"])
+
+
+@receiver(secret_api_token_backup_deleted)
+def revoke_signing_secret_grace_on_backup_deletion(sender, team, deleted_token, **kwargs):
+ """Deleting the legacy backup is an explicit revocation: the same credential must not
+ keep verifying through the signing secret's grace copy. Runs inside the deletion's
+ transaction (Team.delete_secret_token_backup_and_save)."""
+ row = SigningSecret.objects.for_team(team.id).select_for_update().first()
+ if row and row.previous_secret == deleted_token:
+ row.previous_secret = None
+ row.previous_secret_rotated_at = None
+ row.save(update_fields=["previous_secret", "previous_secret_rotated_at"])
diff --git a/products/conversations/backend/tests/test_signing_secret.py b/products/conversations/backend/tests/test_signing_secret.py
index 716f0a32f3a9..a2ec0b6c631d 100644
--- a/products/conversations/backend/tests/test_signing_secret.py
+++ b/products/conversations/backend/tests/test_signing_secret.py
@@ -2,6 +2,7 @@ from posthog.test.base import BaseTest
from unittest.mock import patch
from django.db import OperationalError
+from django.utils import timezone
from parameterized import parameterized
@@ -35,6 +36,77 @@ class TestSigningSecret(BaseTest):
row = SigningSecret.objects.for_team(self.team.id).get()
self.assertEqual(row.secret, self.team.secret_api_token)
self.assertEqual(SigningSecret.objects.for_team(self.team.id).count(), 1)
+ # Legacy grace lives in the backup column; a mirroring row never carries a grace copy.
+ self.assertIsNone(row.previous_secret)
+
+ def test_legacy_rotation_clears_grace_for_a_stale_mirror(self):
+ # A stale mirror holds a retired key; promoting it into the grace copy would
+ # resurrect a credential the staleness guard already excluded.
+ self.team.secret_api_token = "phs_current_token"
+ self.team.save()
+ SigningSecret.objects.for_team(self.team.id).update_or_create(
+ team=self.team,
+ defaults={
+ "secret": "a_retired_secret",
+ "previous_secret": "an_even_older_secret",
+ "previous_secret_rotated_at": timezone.now(),
+ },
+ )
+
+ self.team.rotate_secret_token_and_save(user=self.user, is_impersonated_session=False)
+
+ row = SigningSecret.objects.for_team(self.team.id).get()
+ self.assertEqual(row.secret, self.team.secret_api_token)
+ self.assertIsNone(row.previous_secret)
+ self.assertIsNone(row.previous_secret_rotated_at)
+
+ def test_backup_deletion_revokes_the_grace_copy(self):
+ # Deleting the legacy backup is an explicit revocation; the same credential must
+ # not keep verifying through the signing secret's grace copy.
+ self.team.secret_api_token = "phs_current_token"
+ self.team.secret_api_token_backup = "phs_decoupled_token"
+ self.team.save()
+ SigningSecret.objects.for_team(self.team.id).update_or_create(
+ team=self.team,
+ defaults={
+ "secret": "an_independent_secret",
+ "rotated_independently": True,
+ "previous_secret": "phs_decoupled_token",
+ "previous_secret_rotated_at": timezone.now(),
+ },
+ )
+
+ self.team.delete_secret_token_backup_and_save(user=self.user, is_impersonated_session=False)
+
+ row = SigningSecret.objects.for_team(self.team.id).get()
+ self.assertIsNone(row.previous_secret)
+ self.assertIsNone(row.previous_secret_rotated_at)
+
+ def test_second_legacy_rotation_revokes_the_grace_copy(self):
+ # Revoking a leaked key by rotating the legacy token twice retires it everywhere
+ # else; the independent row's grace copy must die with it.
+ self.team.secret_api_token = "phs_leaked_token"
+ self.team.save()
+ SigningSecret.objects.for_team(self.team.id).update_or_create(
+ team=self.team,
+ defaults={
+ "secret": "an_independent_secret",
+ "rotated_independently": True,
+ "previous_secret": "phs_leaked_token",
+ "previous_secret_rotated_at": timezone.now(),
+ },
+ )
+
+ self.team.rotate_secret_token_and_save(user=self.user, is_impersonated_session=False)
+ row = SigningSecret.objects.for_team(self.team.id).get()
+ self.assertEqual(row.previous_secret, "phs_leaked_token")
+
+ self.team.rotate_secret_token_and_save(user=self.user, is_impersonated_session=False)
+
+ row.refresh_from_db()
+ self.assertIsNone(row.previous_secret)
+ self.assertIsNone(row.previous_secret_rotated_at)
+ self.assertEqual(row.secret, "an_independent_secret")
def test_legacy_rotation_does_not_clobber_an_independent_secret(self):
# A legacy rotation syncing over an independent secret silently breaks verification.
diff --git a/products/conversations/frontend/generated/api.schemas.ts b/products/conversations/frontend/generated/api.schemas.ts
index 590058635930..32c6e2c36448 100644
--- a/products/conversations/frontend/generated/api.schemas.ts
+++ b/products/conversations/frontend/generated/api.schemas.ts
@@ -51,6 +51,11 @@ export interface SigningSecretApi {
* @nullable
*/
readonly updated_at: string | null
+ /**
+ * Until when the previous secret keeps verifying after a rotation, or null when no grace window is active.
+ * @nullable
+ */
+ readonly previous_secret_valid_until: string | null
}
/**
diff --git a/products/conversations/frontend/generated/api.ts b/products/conversations/frontend/generated/api.ts
index 1292bf808581..f7ca63d27fb9 100644
--- a/products/conversations/frontend/generated/api.ts
+++ b/products/conversations/frontend/generated/api.ts
@@ -109,12 +109,29 @@ export const conversationsSigningSecretRetrieve = async (
})
}
+export const getConversationsSigningSecretExpirePreviousCreateUrl = (projectId: string) => {
+ return `/api/projects/${projectId}/conversations/signing_secret/expire_previous/`
+}
+
+/**
+ * End the rotation grace window now: the previous secret stops verifying immediately. Use it when the replaced secret may be compromised, or once every server runs the new one.
+ */
+export const conversationsSigningSecretExpirePreviousCreate = async (
+ projectId: string,
+ options?: RequestInit
+): Promise<SigningSecretApi> => {
+ return apiMutator<SigningSecretApi>(getConversationsSigningSecretExpirePreviousCreateUrl(projectId), {
+ ...options,
+ method: 'POST',
+ })
+}
+
export const getConversationsSigningSecretRotateCreateUrl = (projectId: string) => {
return `/api/projects/${projectId}/conversations/signing_secret/rotate/`
}
/**
- * Generate a new signing secret. Identity hashes signed with the previous secret stop verifying immediately.
+ * Generate a new signing secret. The previous secret keeps verifying identity hashes for 48 hours, then expires.
*/
export const conversationsSigningSecretRotateCreate = async (
projectId: string,
diff --git a/products/conversations/frontend/scenes/settings/IdentityVerificationSecretSection.tsx b/products/conversations/frontend/scenes/settings/IdentityVerificationSecretSection.tsx
index aae04847035a..6b1388b535ee 100644
--- a/products/conversations/frontend/scenes/settings/IdentityVerificationSecretSection.tsx
+++ b/products/conversations/frontend/scenes/settings/IdentityVerificationSecretSection.tsx
@@ -4,6 +4,7 @@ import { IconRefresh } from '@posthog/icons'
import { LemonBanner, LemonCard, LemonSkeleton } from '@posthog/lemon-ui'
import { CodeSnippet } from 'lib/components/CodeSnippet'
+import { TZLabel } from 'lib/components/TZLabel'
import { LemonButton } from 'lib/lemon-ui/LemonButton'
import { LemonDialog } from 'lib/lemon-ui/LemonDialog'
import { teamLogic } from 'scenes/teamLogic'
@@ -14,15 +15,17 @@ import { signingSecretLogic } from './signingSecretLogic'
export function IdentityVerificationSecretSection(): JSX.Element {
const { signingSecret, signingSecretLoading, signingSecretLoadFailed } = useValues(signingSecretLogic)
- const { rotateSigningSecret, loadSigningSecret } = useActions(signingSecretLogic)
+ const { rotateSigningSecret, loadSigningSecret, expirePreviousSecret } = useActions(signingSecretLogic)
const { isTeamTokenResetAvailable } = useValues(teamLogic)
const secret = signingSecret?.secret ?? null
+ // Null once the window lapses: the API only reports an active grace window.
+ const previousSecretValidUntil = signingSecret?.previous_secret_valid_until ?? null
const openRotateDialog = (): void => {
const verb = secret ? 'Rotate' : 'Generate'
const description = secret
- ? 'This generates a new secret right away. Identity hashes signed with the current secret stop verifying immediately, so update your server-side code with the new secret as soon as you rotate.'
+ ? 'This generates a new secret right away. The current secret keeps verifying for 48 hours so you can update your server-side code, then it expires.'
: 'This generates a secret for verifying the identity of users in the support widget.'
LemonDialog.open({
@@ -36,6 +39,20 @@ export function IdentityVerificationSecretSection(): JSX.Element {
})
}
+ const openExpirePreviousDialog = (): void => {
+ LemonDialog.open({
+ title: 'Expire the previous secret now?',
+ description:
+ 'Identity hashes signed with the previous secret stop verifying immediately. Do this if it may be compromised, or once all your servers use the new secret.',
+ primaryButton: {
+ children: 'Expire now',
+ status: 'danger',
+ onClick: expirePreviousSecret,
+ },
+ secondaryButton: { children: 'Cancel' },
+ })
+ }
+
return (
<SceneSection
title="Identity verification secret"
@@ -75,11 +92,28 @@ export function IdentityVerificationSecretSection(): JSX.Element {
'No secret yet. Generate one with the button on the right to enable identity verification.'}
</CodeSnippet>
- {secret ? (
- <LemonBanner type="warning" className="my-2">
- Rotating this secret invalidates identity hashes signed with the current one
- immediately. Rotate if it has been compromised or as part of your regular rotation
- policy, and update your server-side code right after.
+ {previousSecretValidUntil ? (
+ <LemonBanner
+ type="info"
+ className="my-2"
+ action={{
+ children: 'Expire now',
+ 'data-attr': 'conversations-expire-previous-signing-secret',
+ disabledReason: !isTeamTokenResetAvailable
+ ? 'You do not have permission to expire the previous secret'
+ : undefined,
+ onClick: openExpirePreviousDialog,
+ }}
+ >
+ The previous secret keeps verifying until{' '}
+ <TZLabel time={previousSecretValidUntil} formatDate="MMM D, YYYY" formatTime="h:mm A" />
+ . Update your server-side code with the new secret before then, or expire it now if it
+ may be compromised.
+ </LemonBanner>
+ ) : secret ? (
+ <LemonBanner type="info" className="my-2">
+ Rotating this secret starts a 48-hour grace window: the previous secret keeps verifying
+ until the window ends, then expires. Update your server-side code within that window.
</LemonBanner>
) : (
<LemonBanner type="info" className="my-2">
diff --git a/products/conversations/frontend/scenes/settings/signingSecretLogic.ts b/products/conversations/frontend/scenes/settings/signingSecretLogic.ts
index adfaf1b808f6..d787fda1617c 100644
--- a/products/conversations/frontend/scenes/settings/signingSecretLogic.ts
+++ b/products/conversations/frontend/scenes/settings/signingSecretLogic.ts
@@ -3,7 +3,11 @@ import { loaders } from 'kea-loaders'
import { teamLogic } from 'scenes/teamLogic'
-import { conversationsSigningSecretRetrieve, conversationsSigningSecretRotateCreate } from '../../generated/api'
+import {
+ conversationsSigningSecretExpirePreviousCreate,
+ conversationsSigningSecretRetrieve,
+ conversationsSigningSecretRotateCreate,
+} from '../../generated/api'
import type { SigningSecretApi } from '../../generated/api.schemas'
// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
@@ -16,6 +20,21 @@ export interface signingSecretLogicValues {
// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface signingSecretLogicActions {
+ expirePreviousSecret: () => any
+ expirePreviousSecretFailure: (
+ error: string,
+ errorObject?: any
+ ) => {
+ error: string
+ errorObject?: any
+ }
+ expirePreviousSecretSuccess: (
+ signingSecret: SigningSecretApi,
+ payload?: any
+ ) => {
+ signingSecret: SigningSecretApi
+ payload?: any
+ }
loadSigningSecret: () => any
loadSigningSecretFailure: (
error: string,
@@ -60,6 +79,8 @@ export const signingSecretLogic = kea<signingSecretLogicType>([
loadSigningSecret: async () => await conversationsSigningSecretRetrieve(String(values.currentTeamId)),
rotateSigningSecret: async () =>
await conversationsSigningSecretRotateCreate(String(values.currentTeamId)),
+ expirePreviousSecret: async () =>
+ await conversationsSigningSecretExpirePreviousCreate(String(values.currentTeamId)),
},
],
})),
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index e9b9e9f6b419..e63400918596 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -109720,6 +109720,11 @@ export namespace Schemas {
* @nullable
*/
readonly updated_at: string | null;
+ /**
+ * Until when the previous secret keeps verifying after a rotation, or null when no grace window is active.
+ * @nullable
+ */
+ readonly previous_secret_valid_until: string | null;
}
export interface SlackChannel {