diff --git a/README.md b/README.md index d82cb515..018cf391 100644 --- a/README.md +++ b/README.md @@ -253,7 +253,7 @@ await seam.Devices.UpdateAsync(new() Verify and parse incoming Seam webhook events with `SeamWebhook`: ```csharp -var webhook = new SeamWebhook(Environment.GetEnvironmentVariable("SEAM_WEBHOOK_SECRET")!); +var webhook = new SeamWebhook(); // Reads SEAM_WEBHOOK_SECRET. var seamEvent = webhook.Verify(requestBody, requestHeaders); @@ -261,6 +261,12 @@ if (seamEvent is Seam.Models.EventDeviceConnected connected) Console.WriteLine(connected.DeviceId); ``` +Omitting the secret reads `SEAM_WEBHOOK_SECRET` when +the helper is constructed. Pass `new SeamWebhook("whsec_...")` to override +the environment. A missing or empty secret raises `InvalidOperationException` +at construction; explicit null or empty strings never fall back to the environment. +Svix also rejects secrets that decode to an empty signing key. + Verification failures raise Svix's `WebhookVerificationException`: treat the payload as forged and respond with an error status so Svix retries. A payload that is correctly signed but unreadable raises a diff --git a/src/Seam/SeamWebhook.cs b/src/Seam/SeamWebhook.cs index 5430aaab..a9aa88e8 100644 --- a/src/Seam/SeamWebhook.cs +++ b/src/Seam/SeamWebhook.cs @@ -12,7 +12,7 @@ namespace Seam /// by the API. Verification failures raise /// . /// - /// var webhook = new SeamWebhook(Environment.GetEnvironmentVariable("SEAM_WEBHOOK_SECRET")!); + /// var webhook = new SeamWebhook(); // Reads SEAM_WEBHOOK_SECRET. /// var seamEvent = webhook.Verify(requestBody, requestHeaders); /// /// @@ -20,9 +20,31 @@ public sealed class SeamWebhook { private readonly Svix.Webhook _webhook; - /// The webhook secret from the Seam Console. + /// + /// Reads SEAM_WEBHOOK_SECRET at construction time. + /// + /// + /// When the environment secret is missing or empty. + /// + public SeamWebhook() + : this(Environment.GetEnvironmentVariable("SEAM_WEBHOOK_SECRET") ?? "") { } + + /// + /// The webhook secret from the Seam Console. Null and empty strings never fall back + /// to SEAM_WEBHOOK_SECRET. + /// + /// + /// When the secret is missing or empty. + /// public SeamWebhook(string secret) { + if (string.IsNullOrEmpty(secret)) + { + throw new InvalidOperationException( + "Provide a webhook secret or set SEAM_WEBHOOK_SECRET to a non-empty value." + ); + } + _webhook = new Svix.Webhook(secret); } diff --git a/test/Seam.Test/SeamWebhookTests.cs b/test/Seam.Test/SeamWebhookTests.cs index 835b891d..73424b4c 100644 --- a/test/Seam.Test/SeamWebhookTests.cs +++ b/test/Seam.Test/SeamWebhookTests.cs @@ -3,6 +3,7 @@ namespace Seam.Test; using System.Security.Cryptography; using System.Text; using System.Text.Json; +using Seam.Test.Support; using Svix.Exceptions; public class SeamWebhookTests @@ -36,6 +37,80 @@ private static Dictionary SignedHeaders( }; } + [Fact] + public void OmittedSecretReadsEnvironment() + { + using var env = new EnvGuard(); + env.Set("SEAM_WEBHOOK_SECRET", Secret); + + var webhook = new SeamWebhook(); + var seamEvent = webhook.Verify(Payload, SignedHeaders(Payload)); + + Assert.Equal("device.connected", seamEvent.EventType); + } + + [Fact] + public void ExplicitSecretOverridesEnvironment() + { + using var env = new EnvGuard(); + env.Set("SEAM_WEBHOOK_SECRET", "whsec_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="); + + var seamEvent = new SeamWebhook(Secret).Verify(Payload, SignedHeaders(Payload)); + + Assert.Equal("device.connected", seamEvent.EventType); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + public void MissingOrEmptyEnvironmentSecretIsRejected(string? secret) + { + using var env = new EnvGuard(); + if (secret is not null) + env.Set("SEAM_WEBHOOK_SECRET", secret); + + var exception = Assert.Throws(() => new SeamWebhook()); + Assert.Contains("SEAM_WEBHOOK_SECRET", exception.Message); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + public void ExplicitNullOrEmptySecretDoesNotFallBackToEnvironment(string? secret) + { + using var env = new EnvGuard(); + env.Set("SEAM_WEBHOOK_SECRET", Secret); + + Assert.Throws(() => new SeamWebhook(secret!)); + } + + [Theory] + [InlineData("whsec_")] + [InlineData("whsec_ ")] + [InlineData(" ")] + public void EnvironmentSecretWithEmptyDecodedKeyIsRejected(string secret) + { + using var env = new EnvGuard(); + env.Set("SEAM_WEBHOOK_SECRET", secret); + + Assert.Throws(() => new SeamWebhook()); + } + + [Fact] + public void EachConstructionReadsCurrentEnvironment() + { + using var env = new EnvGuard(); + env.Set("SEAM_WEBHOOK_SECRET", Secret); + var first = new SeamWebhook(); + + env.Set("SEAM_WEBHOOK_SECRET", "whsec_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="); + var second = new SeamWebhook(); + var headers = SignedHeaders(Payload); + + Assert.Equal("device.connected", first.Verify(Payload, headers).EventType); + Assert.Throws(() => second.Verify(Payload, headers)); + } + [Fact] public void VerifyReturnsTheEvent() { diff --git a/test/Seam.Test/Support/EnvGuard.cs b/test/Seam.Test/Support/EnvGuard.cs index 34eca79c..436d6a30 100644 --- a/test/Seam.Test/Support/EnvGuard.cs +++ b/test/Seam.Test/Support/EnvGuard.cs @@ -12,6 +12,7 @@ public sealed class EnvGuard : IDisposable "SEAM_PERSONAL_ACCESS_TOKEN", "SEAM_WORKSPACE_ID", "SEAM_ENDPOINT", + "SEAM_WEBHOOK_SECRET", }; private readonly Dictionary _saved = new();