terp-cap-webhooks 0.1.0__tar.gz

terp_cap_webhooks-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.venv-*/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# uv
+uv.lock
+
+# Node
+node_modules/
+.pnpm-store/
+*.tsbuildinfo
+
+# Playwright (conformance e2e) artifacts
+test-results/
+playwright-report/
+blob-report/
+playwright/.cache/
+.last-run.json
+
+# Local frontend template render checks
+apps/example/_frontend_tpl_check/
+
+# Editor / OS
+.DS_Store
+.idea/
+*.local
+
+# Local environment overrides — never commit (a real .env may hold SECRET_KEY).
+# The tracked template is `.env.example`.
+.env
+.env.*
+!.env.example
+!.env.example.jinja
+# Rendered app-declared variables (environment.schema.json) — may hold secrets.
+.app.env

terp_cap_webhooks-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: terp-cap-webhooks
+Version: 0.1.0
+Summary: Terp webhooks capability — reliable, signed, SSRF-guarded outbound webhooks on the jobs/outbox seam.
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: cryptography>=48.0.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: terp-core==0.1.0

terp_cap_webhooks-0.1.0/escape-hatch-budget.json

@@ -0,0 +1,6 @@
+{
+  "arch-allow-mutations-emit-audit": 2,
+  "arch-allow-no-destructive-migrations": 1,
+  "arch-allow-no-internal-imports": 1,
+  "arch-allow-table-models-use-base-table": 1
+}

terp_cap_webhooks-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "terp-cap-webhooks"
+version = "0.1.0"
+description = "Terp webhooks capability — reliable, signed, SSRF-guarded outbound webhooks on the jobs/outbox seam."
+requires-python = ">=3.13"
+license = "Apache-2.0"
+dependencies = [
+    "terp-core==0.1.0",
+    # The outbound HTTP client lives ONLY in this capability (the delivery job handler);
+    # an app module never imports it. Background delivery + retry ride the jobs/outbox seam.
+    "httpx>=0.27",
+    # Seals the subscription signing secret at rest (ADR 0076) — Fernet keyed from
+    # SECRET_KEY with a webhooks-specific HKDF label, mirroring terp.core.secrets.
+    "cryptography>=48.0.1",
+]
+
+# Self-registering: the kernel discovers this ModuleSpec via the entry point, mounting the
+# admin webhooks router at `/api/v1/webhooks` without any composition-root edit.
+[project.entry-points."terp.capabilities"]
+webhooks = "terp.capabilities.webhooks:module"
+
+# Owns the `webhook_subscription` + append-only `webhook_delivery` tables, so it ships an
+# independent, linear Alembic history (its own `alembic_version_webhooks` table). `terp
+# migrate` discovers this via the `terp.migrations` group (ADR 0027).
+[project.entry-points."terp.migrations"]
+webhooks = "terp.capabilities.webhooks"
+
+# PEP 420 namespace package: this distribution owns only `terp.capabilities.webhooks`.
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+only-include = ["src/terp/capabilities/webhooks"]

terp_cap_webhooks-0.1.0/src/terp/capabilities/webhooks/__init__.py

@@ -0,0 +1,104 @@
+"""terp.capabilities.webhooks — reliable, signed, SSRF-guarded outbound webhooks.
+
+Built **only** on the shipped ports: the jobs seam (:func:`terp.core.enqueue` + a typed
+:class:`~terp.core.JobDefinition`) and the durable outbox (for retry / dead-letter). It adds
+no engine and changes no ``terp.core``.
+
+* A consumer registers an owner-scoped :class:`WebhookSubscription` through the discovered,
+  admin-only router at ``/api/v1/webhooks``; the signing ``secret`` is supplied on create and
+  is never serialized back out.
+* An app wires :func:`enqueue_webhook_deliveries` to a catalog event with the eventbus
+  ``@subscribe`` decorator, so when the event fires the matching deliveries are enqueued **on
+  the producer's session** — atomically with the business write (no dual-write).
+* The :data:`WEBHOOK_DELIVER` job (drained by the outbox worker, ``terp jobs worker``) signs
+  the payload (HMAC-SHA256), re-checks the target against the SSRF denylist, POSTs with a
+  strict timeout and no redirect following, records a :class:`WebhookDelivery`, and lets a
+  failure propagate so the outbox retries with backoff and dead-letters.
+
+It depends only on ``terp-core`` and ``httpx`` — never a sibling capability or a broker
+engine; the app composes the durable ``OutboxJobQueue`` at ``create_app``.
+"""
+
+from __future__ import annotations
+
+from terp.capabilities.webhooks.delivery import (
+    WEBHOOK_DELIVER,
+    WebhookDeliveryError,
+    WebhookDeliveryPayload,
+    WebhookResponse,
+    WebhookSender,
+    active_webhook_sender,
+    deliver_webhook,
+    reset_webhook_sender,
+    set_webhook_sender,
+)
+from terp.capabilities.webhooks.models import (
+    OUTCOME_BLOCKED,
+    OUTCOME_DELIVERED,
+    OUTCOME_FAILED,
+    OUTCOME_SKIPPED,
+    WebhookDelivery,
+    WebhookSubscription,
+)
+from terp.capabilities.webhooks.router import module, router
+from terp.capabilities.webhooks.sealing import (
+    WebhookSecretError,
+    is_sealed_secret,
+    seal_secret,
+    unseal_secret,
+)
+from terp.capabilities.webhooks.schemas import (
+    WebhookDeliveryRead,
+    WebhookSubscriptionCreate,
+    WebhookSubscriptionRead,
+    WebhookSubscriptionUpdate,
+)
+from terp.capabilities.webhooks.service import WebhookSubscriptionService, list_deliveries
+from terp.capabilities.webhooks.ssrf import (
+    CLOUD_METADATA_ADDRESS,
+    PinnedTarget,
+    WebhookTargetError,
+    is_denied_address,
+    resolve_pinned_target,
+    validate_webhook_target,
+)
+from terp.capabilities.webhooks.store import record_delivery
+from terp.capabilities.webhooks.triggers import enqueue_webhook_deliveries
+
+__all__ = [
+    "CLOUD_METADATA_ADDRESS",
+    "OUTCOME_BLOCKED",
+    "OUTCOME_DELIVERED",
+    "OUTCOME_FAILED",
+    "OUTCOME_SKIPPED",
+    "WEBHOOK_DELIVER",
+    "PinnedTarget",
+    "WebhookDelivery",
+    "WebhookDeliveryError",
+    "WebhookDeliveryPayload",
+    "WebhookDeliveryRead",
+    "WebhookResponse",
+    "WebhookSecretError",
+    "WebhookSender",
+    "WebhookSubscription",
+    "WebhookSubscriptionCreate",
+    "WebhookSubscriptionRead",
+    "WebhookSubscriptionService",
+    "WebhookSubscriptionUpdate",
+    "WebhookTargetError",
+    "active_webhook_sender",
+    "deliver_webhook",
+    "enqueue_webhook_deliveries",
+    "is_denied_address",
+    "is_sealed_secret",
+    "list_deliveries",
+    "module",
+    "record_delivery",
+    "reset_webhook_sender",
+    "resolve_pinned_target",
+    "router",
+    "seal_secret",
+    "set_webhook_sender",
+    "unseal_secret",
+    "validate_webhook_target",
+]

terp_cap_webhooks-0.1.0/src/terp/capabilities/webhooks/delivery.py

@@ -0,0 +1,315 @@
+"""The ``WEBHOOK_DELIVER`` job: sign + POST one delivery, record the attempt, retry on failure.
+
+This is the worker half of the webhook seam (the jobs design's §6 / §7): the external HTTP
+call lives **here**, in a job handler that runs **post-commit, on a worker**, drained from
+the durable outbox — never in an ``_after_write`` hook (which would dual-write the business
+row and a remote call). The trigger (an event subscriber) only *enqueues* this job, atomically
+with the business write; this handler delivers it off-request, and a failure **propagates** so
+the :class:`~terp.core.RetryPolicy` + outbox worker retry with exponential backoff and
+dead-letter after the attempt budget is spent.
+
+Security controls applied on every attempt:
+
+* an **SSRF re-check** of the target immediately before the request (DNS-rebinding defense,
+  :mod:`terp.capabilities.webhooks.ssrf`);
+* an **HMAC-SHA256** signature over the exact JSON body, keyed by the subscription's stored
+  ``secret`` — which never leaves the server;
+* a strict outbound **timeout**, a bounded outbound **payload size**, and **no redirect
+  following** (a 3xx is recorded as a failure, never chased to a possibly-disallowed host).
+
+The outbound HTTP client is the injectable :data:`WebhookSender` seam (default: ``httpx``),
+so tests drive the handler with no real network I/O — and ``httpx`` is imported only here, in
+this capability, never by an app module.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any, Final
+
+import httpx
+from sqlmodel import Field
+
+from terp.core import (
+    AppError,
+    BaseSchema,
+    JobContext,
+    JobDefinition,
+    JobVisibility,
+    NotFoundError,
+    RetryPolicy,
+)
+
+from terp.capabilities.webhooks.models import (
+    OUTCOME_BLOCKED,
+    OUTCOME_DELIVERED,
+    OUTCOME_FAILED,
+    OUTCOME_SKIPPED,
+)
+from terp.capabilities.webhooks.sealing import WebhookSecretError, unseal_secret
+from terp.capabilities.webhooks.service import WebhookSubscriptionService
+from terp.capabilities.webhooks.ssrf import (
+    PinnedTarget,
+    WebhookTargetError,
+    resolve_pinned_target,
+)
+from terp.capabilities.webhooks.store import record_delivery
+
+# Conservative secure outbound limits (Tier-B-style knobs with safe defaults).
+_TIMEOUT_SECONDS: Final[float] = 10.0
+_MAX_PAYLOAD_BYTES: Final[int] = 256 * 1024  # 256 KiB cap on the signed body
+_SIGNATURE_HEADER: Final[str] = "X-Terp-Signature"
+_TIMESTAMP_HEADER: Final[str] = "X-Terp-Webhook-Timestamp"
+_EVENT_HEADER: Final[str] = "X-Terp-Event"
+_DELIVERY_HEADER: Final[str] = "X-Terp-Delivery-Id"
+
+
+def _utc_now() -> datetime:
+    """UTC ``now`` provider for the signature timestamp (private so tests can patch it)."""
+    return datetime.now(UTC)
+
+
+class WebhookDeliveryError(AppError):
+    """502 — a webhook delivery attempt failed; propagated so the outbox retries / dead-letters."""
+
+    status_code = 502
+    code = "webhook_delivery_failed"
+    default_message = "The webhook endpoint did not accept the delivery."
+
+
+class WebhookDeliveryPayload(BaseSchema):
+    """The JSON-serializable payload carried by a ``WEBHOOK_DELIVER`` job (ids, not entities).
+
+    It carries the subscription id (the handler re-loads the live row to read the current
+    target / secret — neither rides the wire), a per-attempt-stable ``delivery_id`` the
+    subscriber can dedupe on, the originating event name, and the event's public ``data``.
+    """
+
+    subscription_id: uuid.UUID
+    delivery_id: uuid.UUID
+    event: str = Field(max_length=128)
+    data: dict[str, Any] = Field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class WebhookResponse:
+    """The minimal result the handler needs from an outbound POST (the status code)."""
+
+    status_code: int
+
+
+# A sender performs the actual POST and returns a :class:`WebhookResponse`. It is injectable
+# so tests drive the handler without real network I/O (mirroring the audit-sink / throttle-
+# store seams); the default implementation uses ``httpx``.
+WebhookSender = Callable[[PinnedTarget, bytes, dict[str, str]], WebhookResponse]
+
+
+def _httpx_sender(
+    target: PinnedTarget, body: bytes, headers: dict[str, str]
+) -> WebhookResponse:
+    """Default sender: POST to *target*, pinned to its pre-validated IP, no redirect chasing.
+
+    The request is built from the original ``https`` URL (so the ``Host`` header + path are
+    correct and TLS is verified against the hostname via the ``sni_hostname`` extension), then
+    the connection is **repointed to the validated IP** — so a DNS-rebinding attacker cannot
+    make the socket land on a private address after the SSRF check (closing the TOCTOU). A
+    strict timeout bounds the request; redirects are never followed.
+    """
+    with httpx.Client(timeout=_TIMEOUT_SECONDS, follow_redirects=False) as client:
+        request = client.build_request(
+            "POST",
+            target.url,
+            content=body,
+            headers=headers,
+            extensions={"sni_hostname": target.host},
+        )
+        request.url = request.url.copy_with(host=target.ip)
+        response = client.send(request)
+    return WebhookResponse(status_code=response.status_code)
+
+
+_active_sender: WebhookSender = _httpx_sender
+
+
+def set_webhook_sender(sender: WebhookSender) -> None:
+    """Install the outbound HTTP *sender* (the seam tests replace with a fake)."""
+    global _active_sender
+    _active_sender = sender
+
+
+def reset_webhook_sender() -> None:
+    """Restore the default ``httpx`` sender (the test-isolation reset)."""
+    global _active_sender
+    _active_sender = _httpx_sender
+
+
+def active_webhook_sender() -> WebhookSender:
+    """The sender the delivery handler currently posts through."""
+    return _active_sender
+
+
+def _sign(secret: str, timestamp: str, body: bytes) -> str:
+    """``sha256=<hex>`` HMAC-SHA256 over ``timestamp.body``, keyed by the subscription *secret*.
+
+    Binding the timestamp into the signature lets a receiver reject a **replay** of a captured
+    delivery: it recomputes the HMAC over the ``X-Terp-Webhook-Timestamp`` header value and the
+    raw body and bounds the age, so a valid signature is not indefinitely reusable.
+    """
+    signed = timestamp.encode("utf-8") + b"." + body
+    digest = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
+    return f"sha256={digest}"
+
+
+_service = WebhookSubscriptionService()
+
+
+def deliver_webhook(ctx: JobContext, payload: WebhookDeliveryPayload) -> None:
+    """Deliver one webhook: load the subscription, sign, POST, record the attempt.
+
+    Runs in its own audited unit on a worker (``run_job``). A non-2xx response or a network
+    error records a ``failed`` attempt and then **raises** :class:`WebhookDeliveryError`, so
+    the outbox retries with backoff and dead-letters after the job's ``RetryPolicy`` budget.
+    A removed / inactive subscription, an SSRF-blocked target, or an oversized payload records
+    a terminal attempt and returns without raising (a retry could not help).
+    """
+    try:
+        subscription = _service.get(ctx.session, payload.subscription_id)
+    except NotFoundError:
+        record_delivery(
+            ctx.session,
+            subscription_id=payload.subscription_id,
+            event=payload.event,
+            outcome=OUTCOME_SKIPPED,
+            attempt=ctx.attempt,
+            last_error="subscription no longer exists",
+        )
+        return
+    if not subscription.active:
+        record_delivery(
+            ctx.session,
+            subscription_id=subscription.id,
+            event=payload.event,
+            outcome=OUTCOME_SKIPPED,
+            attempt=ctx.attempt,
+            last_error="subscription is inactive",
+        )
+        return
+
+    body = json.dumps(payload.data, separators=(",", ":"), sort_keys=True).encode("utf-8")
+    if len(body) > _MAX_PAYLOAD_BYTES:
+        record_delivery(
+            ctx.session,
+            subscription_id=subscription.id,
+            event=payload.event,
+            outcome=OUTCOME_FAILED,
+            attempt=ctx.attempt,
+            last_error=f"payload exceeds the {_MAX_PAYLOAD_BYTES}-byte cap",
+        )
+        return  # an oversized payload is deterministic — do not waste retries on it
+
+    try:
+        pinned = resolve_pinned_target(subscription.target_url)
+    except WebhookTargetError as exc:
+        record_delivery(
+            ctx.session,
+            subscription_id=subscription.id,
+            event=payload.event,
+            outcome=OUTCOME_BLOCKED,
+            attempt=ctx.attempt,
+            last_error=exc.message,
+        )
+        return  # an SSRF-blocked target is deterministic — do not retry it
+
+    try:
+        # Sealed at rest (ADR 0076): the plaintext exists only here, at signing time.
+        signing_secret = unseal_secret(subscription.secret)
+    except WebhookSecretError as exc:
+        record_delivery(
+            ctx.session,
+            subscription_id=subscription.id,
+            event=payload.event,
+            outcome=OUTCOME_FAILED,
+            attempt=ctx.attempt,
+            last_error=exc.message,
+        )
+        return  # a secret that no longer unseals is deterministic — do not retry it
+
+    timestamp = str(int(_utc_now().timestamp()))
+    headers = {
+        "Content-Type": "application/json",
+        _TIMESTAMP_HEADER: timestamp,
+        _SIGNATURE_HEADER: _sign(signing_secret, timestamp, body),
+        _EVENT_HEADER: payload.event,
+        _DELIVERY_HEADER: str(payload.delivery_id),
+    }
+    try:
+        response = active_webhook_sender()(pinned, body, headers)
+    except Exception as exc:  # noqa: BLE001 - any transport error becomes a recorded, retried failure
+        record_delivery(
+            ctx.session,
+            subscription_id=subscription.id,
+            event=payload.event,
+            outcome=OUTCOME_FAILED,
+            response_code=None,
+            attempt=ctx.attempt,
+            last_error=f"request error: {exc}",
+        )
+        raise WebhookDeliveryError(
+            f"webhook request to subscription {subscription.id} failed"
+        ) from exc
+
+    if 200 <= response.status_code < 300:
+        record_delivery(
+            ctx.session,
+            subscription_id=subscription.id,
+            event=payload.event,
+            outcome=OUTCOME_DELIVERED,
+            response_code=response.status_code,
+            attempt=ctx.attempt,
+        )
+        return
+    record_delivery(
+        ctx.session,
+        subscription_id=subscription.id,
+        event=payload.event,
+        outcome=OUTCOME_FAILED,
+        response_code=response.status_code,
+        attempt=ctx.attempt,
+        last_error=f"endpoint returned HTTP {response.status_code}",
+    )
+    raise WebhookDeliveryError(
+        f"webhook delivery to subscription {subscription.id} failed with "
+        f"HTTP {response.status_code}"
+    )
+
+
+# The typed job contract a consumer wires into its control-plane ``JobCatalog`` so the
+# trigger can enqueue it (and the outbox worker resolve its handler by name). Retries lean
+# on the outbox: five attempts with exponential backoff, then dead-letter.
+WEBHOOK_DELIVER = JobDefinition(
+    name="webhooks.delivery.send",
+    payload_schema=WebhookDeliveryPayload,
+    handler=deliver_webhook,
+    retry=RetryPolicy(max_attempts=5, backoff_seconds=10.0),
+    queue="webhooks",
+    visibility=JobVisibility.INTERNAL,
+)
+
+
+__all__ = [
+    "WEBHOOK_DELIVER",
+    "WebhookDeliveryError",
+    "WebhookDeliveryPayload",
+    "WebhookResponse",
+    "WebhookSender",
+    "active_webhook_sender",
+    "deliver_webhook",
+    "reset_webhook_sender",
+    "set_webhook_sender",
+]

terp_cap_webhooks-0.1.0/src/terp/capabilities/webhooks/migrations/versions/717754ab63f6_create_webhooks_tables.py

@@ -0,0 +1,80 @@
+"""create webhooks tables
+
+Revision ID: 717754ab63f6
+Revises: 
+Create Date: 2026-06-30 22:16:37.385448
+
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+
+# revision identifiers, used by Alembic.
+revision: str = '717754ab63f6'
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('webhook_delivery',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('subscription_id', sa.Uuid(), nullable=False),
+    sa.Column('event', sqlmodel.sql.sqltypes.AutoString(length=128), nullable=False),
+    sa.Column('outcome', sqlmodel.sql.sqltypes.AutoString(length=16), nullable=False),
+    sa.Column('response_code', sa.Integer(), nullable=True),
+    sa.Column('attempt', sa.Integer(), nullable=False),
+    sa.Column('last_error', sqlmodel.sql.sqltypes.AutoString(length=2000), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_webhook_delivery'))
+    )
+    with op.batch_alter_table('webhook_delivery', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_webhook_delivery_created_at'), ['created_at'], unique=False)
+        batch_op.create_index(batch_op.f('ix_webhook_delivery_event'), ['event'], unique=False)
+        batch_op.create_index(batch_op.f('ix_webhook_delivery_outcome'), ['outcome'], unique=False)
+        batch_op.create_index(batch_op.f('ix_webhook_delivery_subscription_id'), ['subscription_id'], unique=False)
+
+    op.create_table('webhook_subscription',
+    sa.Column('owner_id', sa.Uuid(), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('version', sa.Integer(), nullable=False),
+    sa.Column('target_url', sqlmodel.sql.sqltypes.AutoString(length=2048), nullable=False),
+    sa.Column('secret', sqlmodel.sql.sqltypes.AutoString(length=256), nullable=False),
+    sa.Column('event', sqlmodel.sql.sqltypes.AutoString(length=128), nullable=False),
+    sa.Column('active', sa.Boolean(), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_webhook_subscription'))
+    )
+    with op.batch_alter_table('webhook_subscription', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_webhook_subscription_active'), ['active'], unique=False)
+        batch_op.create_index(batch_op.f('ix_webhook_subscription_event'), ['event'], unique=False)
+        batch_op.create_index(batch_op.f('ix_webhook_subscription_owner_id'), ['owner_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_webhook_subscription_target_url'), ['target_url'], unique=False)
+
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table('webhook_subscription', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_webhook_subscription_target_url'))
+        batch_op.drop_index(batch_op.f('ix_webhook_subscription_owner_id'))
+        batch_op.drop_index(batch_op.f('ix_webhook_subscription_event'))
+        batch_op.drop_index(batch_op.f('ix_webhook_subscription_active'))
+
+    op.drop_table('webhook_subscription')
+    with op.batch_alter_table('webhook_delivery', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_webhook_delivery_subscription_id'))
+        batch_op.drop_index(batch_op.f('ix_webhook_delivery_outcome'))
+        batch_op.drop_index(batch_op.f('ix_webhook_delivery_event'))
+        batch_op.drop_index(batch_op.f('ix_webhook_delivery_created_at'))
+
+    op.drop_table('webhook_delivery')
+    # ### end Alembic commands ###

terp_cap_webhooks-0.1.0/src/terp/capabilities/webhooks/migrations/versions/8f1c4a2d9b3e_widen_webhook_secret_for_sealing.py

@@ -0,0 +1,48 @@
+"""widen webhook secret for at-rest sealing
+
+Revision ID: 8f1c4a2d9b3e
+Revises: 717754ab63f6
+Create Date: 2026-07-06 20:30:00.000000
+
+The subscription's signing ``secret`` is now sealed before it is persisted
+(ADR 0076): the stored value is the ``enc:v1:`` Fernet ciphertext of the
+client-supplied secret, whose seal of the schema's 256-char maximum input is
+~447 characters — so the column widens from 256 to 512. A widening VARCHAR
+change loses no data; existing (legacy plaintext) rows are untouched and keep
+delivering — the runtime unseal passes an unsealed value through unchanged.
+"""
+# terp-allow-destructive-migration: widening webhook_subscription.secret 256 -> 512 (a pure widen — no value can be truncated) so the sealed-at-rest ciphertext fits (ADR 0076)
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlmodel
+
+
+# revision identifiers, used by Alembic.
+revision: str = '8f1c4a2d9b3e'
+down_revision: str | None = '717754ab63f6'
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table('webhook_subscription', schema=None) as batch_op:
+        # arch-allow-no-destructive-migrations: widening secret 256 -> 512 (a pure widen — no value can be truncated) so the sealed-at-rest ciphertext fits (ADR 0076)
+        batch_op.alter_column(
+            'secret',
+            existing_type=sqlmodel.sql.sqltypes.AutoString(length=256),
+            type_=sqlmodel.sql.sqltypes.AutoString(length=512),
+            existing_nullable=False,
+        )
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('webhook_subscription', schema=None) as batch_op:
+        batch_op.alter_column(
+            'secret',
+            existing_type=sqlmodel.sql.sqltypes.AutoString(length=512),
+            type_=sqlmodel.sql.sqltypes.AutoString(length=256),
+            existing_nullable=False,
+        )