The Slack Integration — identity, credentials, and what revocation actually means

Every claim here is cited to code. Where a behaviour is defended by a test or a CI guard, the
guard is named. Where a mitigation lives outside this repo, it says so. Where something is
best-effort, it says best-effort.

If you are here because something broke#

The identity model#

The principal is an opaque string#

Three checks, all shape and none semantic: non-empty, within the storage column's width, and
carrying the slack: prefix. The principal is OPAQUE — 2 to 4 segments … so it is deliberately
NEVER split on ':'. A prefix check plus a length check is the whole of what is knowable without
parsing something we have no business parsing.

The binding lives in kb_profile_auth_links#

Why the link is keyed on the principal and not email#

email stays NULL: Slack supplies no email on the wire, which is exactly why the link is keyed
on the opaque principal.

Linking is lookup-only#

the latter auto-provisions a profile, which on a stray click would mint an account and confer
auto-join team reach. Linking an existing identity is not a registration route.

The four credentials, and what each is worth#

Why the link secret and the mint secret are deliberately different#

This is the highest-privilege gate in the file, and the reason it has its own key. The other
two guard endpoints that report something … This one guards an endpoint that hands back an
act-as-the-human access token … The endpoint that confers reach cannot share a key with
one that merely answers a question, however convenient one variable would be. Same scheme, third
key.

A consequence worth internalising: a test that calls mint_for_mention directly and passes has
proved nothing about authorization. The test must drive the route.

Collapsing two of these onto one config field is a one-line edit that no type checks, no route
audit notices (all three layers are still mounted, so audit-route-auth.sh stays green), and —
until this script — nothing in CI caught. It was defended only by an e2e test, i.e. only where
someone remembered to look.

Trust boundaries#

[Slack workspace]                          ← untrusted; anyone in the workspace can type anything
      │  POST /eve/v1/slack
      │  ── verified by: Slack request signature (SLACK_SIGNING_SECRET), HMAC over the raw body
      ▼
[eve runtime, in the mention agent]        ← boundary 1
      │  verifyInbound() is the FIRST statement of the route; failure ⇒ 401 before any dispatch
      │  principalId is derived HERE, by eve, from the verified event
      ▼
[agent handler: onAppMention]              ← boundary 2 (policy, not authentication)
      │  decideIdentity(): principalType === "user" or drop; bots surface as "service"
      │  body = { slack_principal_id } and NOTHING else
      │  ── signed with: HMAC-SHA256(secret, "{timestamp}.{body}") → X-Temper-Signature
      ▼
[temper-api /internal/slack/{link-state,mint}]   ← boundary 3
      │  require_slack_link_signature | require_slack_mint_signature
      │  fresh timestamp (±30s) + constant-time MAC over the exact bytes received
      ▼
[services → DB]                            ← boundary 4
         resources_visible_to / can_modify_resource scope every query to the profile

Fail-closed behaviours#

Deployment and secret sequencing#

The trap: two Slack secrets with opposite rules#

⚠️ This is the pattern-match hazard in this feature. Two SLACK_* secrets have opposite
deployment rules, and they look alike enough that treating them the same way is the natural
mistake. Read this before touching either.

Which deployments this actually lives on#

The server half is temper-cloud, not temper-api. Those name a crate and two different
Vercel projects, and they are not the same target:

Vercel project	What it is	Slack?
temper-cloud	the temperkb.io community deployment	Yes — every Slack variable below goes here
temper-mention	the @temper mention agent (packages/agent-workflows/mention)	Yes — the agent-side variables
temper-api	the enterprise deployment	No — no Slack piece is deployed here yet

"Deploy temper-api" is the right sentence about the crate and the wrong one about the
environment. Set Slack variables on temper-cloud.

Vercel does not rebuild on an environment-variable change. After setting any of these,
trigger a redeploy or the running function keeps the old values — and a build-time variable like
TEMPER_MCP_URL will keep failing until you do.

On generating SLACK_MINT_SECRET: openssl rand -base64 32 is right, but note it is an
opaque string — verify(secret.as_bytes(), …) (internal_auth.rs:82) and
createHmac("sha256", secret) (link.ts:20) both consume it raw. It is never base64-decoded,
so the trailing = is part of the secret, not encoding to strip.

Do not carry this reasoning to SLACK_VAULT_ENC_KEY, which is decoded
(VaultKey::from_base64, config.rs:207) and must be exactly 32 bytes. Two base64-looking Slack
secrets, only one of them actually base64. A mismatched mint secret is a 401 on every mention,
silent — not a warning, not a degraded mode.

Revocation: what "disconnect" actually stops#

Why an issued token survives#

"Disconnected" means "cannot mint again". It does NOT mean "cannot act".#

Disconnect is not an offboarding control. A token issued moments before the disconnect keeps
working until its own exp. To actually cut someone off, deactivate the profile — that is
enforced per request, at latency 0, on every surface. The CLI says as much on stderr
(crates/temper-cli/src/commands/admin_slack.rs): "disconnect unbinds an identity, it does not
deactivate an account."

How long is "up to its full TTL"?#

AT_REFRESH_SKEW is a FLOOR, not a ceiling#

The mint outcomes, and why the refusal is typed#

{ "status": "token",   "access_token": "…", "expires_at_ms": 1784505600000 }
{ "status": "refused", "reason": "not_linked" }
{ "status": "refused", "reason": "not_vaulted" }
{ "status": "refused", "reason": "standing", "refusal": { "kind": "denied" } }

Known residual risks#

1. First-link URL theft — open by design, bounded#

The sting is in the tail. The no-rebind guard that closes the already-linked case makes a
wrong first binding unrecoverable by the victim — they cannot link, because the principal is
taken, and they cannot unbind it, because they do not own it. Recovery requires
temper admin slack disconnect by a system admin. The refusal page names this (it admits the
principal is linked, a deliberate bounded disclosure) but the other profile's handle is never
revealed (slack_link.rs:252-269).

2. internal_sig binds neither method nor path — key separation is the sole defence#

The two-merge-site hazard is itself defended, and the story is instructive. Because each
layer name appears twice in routes.rs, deleting one of the two mounts left the name still
present elsewhere in the file — so a whole-file grep -q stayed green through exactly that
edit, while one deployed surface served the route ungated. audit-route-auth.sh:152-158 now
asserts the layer per builder (require_layer_in ... $APP_BUILDERS). Its own rationale is
blunt about the stakes: "For slack_mint that is not a downgrade to authenticated-but-broad, it
is act-as-any-user."

3. A signed request is replayable within the skew window — accepted#

4. The IdP refresh-token rotation dual-write window — deliberate; mitigated only out-of-repo#

No row lock can make an external HTTP effect atomic with a local commit.

The mitigation is an Auth0 refresh-token-rotation leeway setting, and nothing in this repo
verifies it is enabled. It is out-of-repo configuration, asserted by neither a test nor a CI
guard nor a startup check. An operator who skips slack-setup.md
§ Step 1.4 gets no warning — only
occasional users whose grant bricks. Recovery in that case is a re-link.

5. Credential-bearing types and derived Debug — closed, and now guarded#

6. Vault key rotation is a flag day — accepted#

What defends these claims#

Related#